From ce903c1ea963da74f4d6a9be2615c7a04cecd530 Mon Sep 17 00:00:00 2001
From: JohnDoe6345789 <john.doe6345789@gmail.com>
Date: Fri, 26 Dec 2025 01:19:40 +0000
Subject: [PATCH] docs: tsx,script,permissions (4 files)

---
 .../entities/lua-script/get-lua-script.ts     | 25 ++++++++++-------
 docs/INDEX.md                                 |  1 +
 docs/permissions-levels.md                    | 28 +++++++++++++++++++
 .../src/app/levels/LevelsClient.test.tsx      | 14 ++++++++++
 4 files changed, 58 insertions(+), 10 deletions(-)
 create mode 100644 docs/permissions-levels.md
 create mode 100644 frontends/nextjs/src/app/levels/LevelsClient.test.tsx

diff --git a/dbal/ts/src/core/entities/lua-script/get-lua-script.ts b/dbal/ts/src/core/entities/lua-script/get-lua-script.ts
index f5369b816..5bece941b 100644
--- a/dbal/ts/src/core/entities/lua-script/get-lua-script.ts
+++ b/dbal/ts/src/core/entities/lua-script/get-lua-script.ts
@@ -2,21 +2,26 @@
  * @file get-lua-script.ts
  * @description Get Lua script operation
  */
-import type { LuaScript, Result } from '../types';
-import type { InMemoryStore } from '../store/in-memory-store';
+import type { DBALAdapter } from '../../../adapters/adapter'
+import type { LuaScript } from '../../types'
+import { DBALError } from '../../errors'
+import { validateId } from '../../validation'
 
 /**
  * Get a Lua script by ID
  */
-export async function getLuaScript(store: InMemoryStore, id: string): Promise<Result<LuaScript>> {
-  if (!id) {
-    return { success: false, error: { code: 'VALIDATION_ERROR', message: 'ID required' } };
+export async function getLuaScript(adapter: DBALAdapter, id: string): Promise<LuaScript> {
+  const validationErrors = validateId(id)
+  if (validationErrors.length > 0) {
+    throw DBALError.validationError(
+      'Invalid Lua script ID',
+      validationErrors.map(error => ({ field: 'id', error }))
+    )
   }
 
-  const script = store.luaScripts.get(id);
-  if (!script) {
-    return { success: false, error: { code: 'NOT_FOUND', message: `Lua script not found: ${id}` } };
+  const result = await adapter.read('LuaScript', id) as LuaScript | null
+  if (!result) {
+    throw DBALError.notFound(`Lua script not found: ${id}`)
   }
-
-  return { success: true, data: script };
+  return result
 }
diff --git a/docs/INDEX.md b/docs/INDEX.md
index 186b6c485..f592dcd5b 100644
--- a/docs/INDEX.md
+++ b/docs/INDEX.md
@@ -48,6 +48,7 @@ Detailed implementation documentation:
 - **[Prisma Implementation](./implementation/PRISMA_IMPLEMENTATION_COMPLETE.md)** - ORM setup
 - **[TypeScript Enhancements](./implementation/TYPESCRIPT_DBAL_ENHANCEMENTS.md)** - Type system improvements
 - **[Nerd Mode IDE](./implementation/NERD_MODE_IDE.md)** - Package templates and zip exports
+- **[Permission Levels](./permissions-levels.md)** - Five-tier security and UI guide
 - **[Codegen Studio Export](./codegen-studio.md)** - Zip generation service for package starters
 
 ### 🔄 [Refactoring](./refactoring/)
diff --git a/docs/permissions-levels.md b/docs/permissions-levels.md
new file mode 100644
index 000000000..101ec2ba2
--- /dev/null
+++ b/docs/permissions-levels.md
@@ -0,0 +1,28 @@
+# Permission Levels Reference
+
+MetaBuilder runs on a five-tier permission stack that spans the public surface, authenticated experiences, moderation, system design, and governance.
+
+## Tier breakdown
+
+| Level | Name | Responsibilities |
+|-------|------|------------------|
+| 1 | Guest | Browse marketing content, view stories, consume public dashboards without any write access.
+| 2 | Regular User | Maintain a profile, tune personal settings, launch saved dashboards, and participate in public workflows.
+| 3 | Moderator | Keep the community healthy by resolving flags, reviewing reports, and adjusting shared spaces.
+| 4 | God | Author blueprints, edit the front page, seed packages, and design workflows for the multiverse.
+| 5 | Super God | Transfer front page ownership, promote gods, run audits, and override safety nets when necessary.
+
+## Interactive view
+
+Visit `/levels` to step through each tier. The page renders a grid of cards, highlights the selected level, and previews the bundle of privileges that accompany it. A promotion button demonstrates the jump to the next level while providing contextual messaging.
+
+## Tooling
+
+- Run `tsx tools/list-permissions.ts` to dump the level definitions and capabilities into the console. This script ensures workflows or automation agents always align with the same data that powers the UI.
+- The CLI at `packages/codegen_studio/static_content/cli/main.cpp --levels` also prints this list so legacy tooling and C++ guardians share the same glossary.
+
+## Testing
+
+- `frontends/nextjs/src/app/levels/LevelsClient.test.tsx` asserts the UI renders each tier and that promotions update the alert banner.
+
+Keeping these references synchronized prevents drift between documentation, UI, tooling, and C++ listeners.
diff --git a/frontends/nextjs/src/app/levels/LevelsClient.test.tsx b/frontends/nextjs/src/app/levels/LevelsClient.test.tsx
new file mode 100644
index 000000000..b09cdfee8
--- /dev/null
+++ b/frontends/nextjs/src/app/levels/LevelsClient.test.tsx
@@ -0,0 +1,14 @@
+import { fireEvent, render, screen } from '@testing-library/react'
+import LevelsClient from './LevelsClient'
+
+describe('LevelsClient', () => {
+  it('renders permission levels and promotes to the next tier', () => {
+    render(<LevelsClient />)
+    expect(screen.getByText(/Level 1 · Guest/)).toBeInTheDocument()
+
+    const promoteButton = screen.getByRole('button', { name: /Promote to/ })
+    fireEvent.click(promoteButton)
+
+    expect(screen.getByText(/Upgraded to Regular User/)).toBeInTheDocument()
+  })
+})