kl3inIT · kl3inIT · Jul 29, 2026 · Jul 29, 2026 · Jul 29, 2026 · coderabbitai
diff --git a/apps/docs/ARCHITECTURE.md b/apps/docs/ARCHITECTURE.md
@@ -3,6 +3,9 @@
 `apps/docs` is an independent Next.js 16 application using Fumadocs UI 16 and
 Fumadocs MDX 15. It owns the public reader experience and has no runtime
 dependency on the product API, worker, MCP server, CLI, or Vite web application.
+Local authoring therefore starts only this package and uses Next.js hot reload;
+no product environment file, database, identity provider, authorization
+service, or Compose stack is required.
 
 ## Current Boundaries
 
@@ -30,8 +33,10 @@ The root pnpm workspace owns dependency installation and the lockfile.
 Turbopack is Next.js 16's default bundler; no explicit flag or Turborepo layer is
 required.
 
-The five root folders are the reader's high-level mode switcher: Start Here,
-System Design, Deploy & Operate, Govern & Administer, and Build & Integrate.
+The four root folders are the reader's high-level mode switcher: Getting
+Started, Guides, Architecture & Security, and Reference. Guides groups product,
+administration, deployment/operations, and integration procedures until one
+subgroup has enough reviewed content and reader demand to justify promotion.
 Their Vietnamese labels come from adjacent `meta.vi.json` files. A Vietnamese
 route may inherit reviewed English content until its matching `.vi.mdx` is
 authored; the reader shows that fallback state explicitly.

diff --git a/apps/docs/AUTHORING.md b/apps/docs/AUTHORING.md
@@ -0,0 +1,165 @@
+# OrgMemory Public Docs Authoring Program
+
+This is the durable page register and working agreement for the long-running
+OrgMemory documentation program. The project owner co-authors one page at a
+time so that improving the docs also improves their architectural
+understanding.
+
+## Working Agreement
+
+- One content increment owns one conceptual page and its adjacent reviewed
+  English/Vietnamese pair.
+- Do not bulk-rewrite, bulk-translate, or create placeholder pages.
+- Before prose, inspect the current repository and runtime evidence and agree
+  on the reader question and outline.
+- English establishes the approved meaning. Vietnamese follows after English
+  review and preserves that meaning naturally.
+- The owner context, outline, and teach-back checkpoints require owner
+  participation. Branch, CI, merge, build, deploy, and live verification may
+  continue autonomously after approval.
+- Public product docs do not publish raw SRS, SDD, ADR, increment, test,
+  runbook, infrastructure, or thesis material.
+
+## Local-First Review Loop
+
+The docs application has no runtime dependency on the OrgMemory product
+services. After the one-time frozen install, start only the docs reader:
+
+```powershell
+corepack pnpm install --frozen-lockfile
+corepack pnpm docs:dev
+```
+
+Review at `http://localhost:3000`. Editing MDX, metadata, styles, or navigation
+uses Next.js hot reload; do not start the API, worker, MCP server, database,
+Keycloak, OpenFGA, product web application, or Docker Compose for ordinary
+content review.
+
+For a draft-only page, use a local preview session:
+
+```powershell
+$env:DOCS_INCLUDE_DRAFTS = 'true'
+corepack pnpm docs:dev
+# Press Ctrl+C to stop the preview server before cleaning the parent shell.
+Remove-Item Env:DOCS_INCLUDE_DRAFTS
+```
+
+The owner should use this fast local loop for the context, outline, English,
+teach-back, and Vietnamese checkpoints. Production publication still requires
+the full repository gates and immutable release loop.
+
+## Target Navigation
+
+```text
+Getting Started
+├── What is OrgMemory?
+├── Quickstart
+├── Core concepts
+└── Terminology
+
+Guides
+├── Using OrgMemory
+│   ├── Browse governed assets
+│   ├── Search organizational knowledge
+│   ├── Ask with Assistant
+│   ├── Verify citations
+│   └── Explore the knowledge graph
+├── Administration
+│   ├── Connect and synchronize a source
+│   ├── Manage users and identities
+│   ├── Configure roles and permissions
+│   └── Audit effective access
+├── Deployment & Operations
+│   ├── Self-host OrgMemory
+│   ├── Configure secrets and environment
+│   ├── Monitor system health
+│   ├── Back up and restore
+│   ├── Upgrade and roll back
+│   └── Troubleshooting
+└── Integrations
+    ├── Connect an MCP client
+    ├── Integrate the Assistant
+    └── Ingest documents through the API
+
+Architecture & Security
+├── System context
+├── Runtime components
+├── Domain and data model
+├── Governed Asset lifecycle
+├── Ingestion and indexing
+├── Identity and authorization
+├── Secure retrieval and GraphRAG
+├── Trust boundaries and threat model
+└── Deployment topology
+
+Reference
+├── API overview
+├── Authentication and errors
+├── API endpoint groups
+├── Configuration variables
+├── Connector capability matrix
+├── Roles and permissions matrix
+├── MCP tools and resources
+├── Error and status codes
+└── Known limitations
+```
+
+Changelog is a global navigation link. Deployment & Operations becomes a root
+only after reviewed content and reader demand justify promotion.
+
+## Authoring Queue
+
+Navigation order serves readers; authoring order stabilizes the system model
+before task procedures depend on it.
+
+| Order | Page | Target location | Current evidence | State |
+| ---: | --- | --- | --- | --- |
+| 1 | What is OrgMemory? | Getting Started | `getting-started/index.mdx` | next |
+| 2 | Core concepts | Getting Started | `getting-started/core-concepts.mdx` | review |
+| 3 | System context | Architecture & Security | `architecture-security/system-description.mdx` | review |
+| 4 | Domain and data model | Architecture & Security | domain specs and schema | missing |
+| 5 | Governed Asset lifecycle | Architecture & Security | `architecture-security/asset-lifecycle.mdx` | review |
+| 6 | Quickstart | Getting Started | `getting-started/quickstart.mdx` | review |
+| 7 | Ingestion and indexing | Architecture & Security | `architecture-security/ingestion-lifecycle.mdx` | review |
+| 8 | Identity and authorization | Architecture & Security | `architecture-security/authorization.mdx` | review |
+| 9 | Secure retrieval and GraphRAG | Architecture & Security | `architecture-security/secure-retrieval-graphrag.mdx` | review |
+| 10 | Runtime components | Architecture & Security | system description and `ARCHITECTURE.md` | missing |
+| 11 | Trust boundaries and threat model | Architecture & Security | security decisions/specs | missing |
+| 12 | Browse governed assets | Guides / Using OrgMemory | product behavior and tests | missing |
+| 13 | Search organizational knowledge | Guides / Using OrgMemory | search contracts and tests | missing |
+| 14 | Ask with Assistant and verify citations | Guides / Using OrgMemory | Assistant/MCP specs and tests | missing |
+| 15 | Explore the knowledge graph | Guides / Using OrgMemory | graph viewer behavior and tests | missing |
+| 16 | Connect and synchronize a source | Guides / Administration | `guides/administration/sources-connections.mdx` | review |
+| 17 | Manage identities and permissions | Guides / Administration | `guides/administration/identity-permissions.mdx` | split and review |
+| 18 | Audit effective access | Guides / Administration | permission evidence specs/tests | missing |
+| 19 | Self-host OrgMemory | Guides / Deployment & Operations | `guides/deployment-operations/self-hosting.mdx` | review |
+| 20 | Configuration and secrets | Guides / Deployment & Operations | environment contracts/runbooks | missing |
+| 21 | Observability and health | Guides / Deployment & Operations | deployment and telemetry evidence | missing |
+| 22 | Backup, restore, upgrade, and rollback | Guides / Deployment & Operations | runbooks and release workflows | split later |
+| 23 | Connect an MCP client | Guides / Integrations | `guides/integrations/assistant-mcp.mdx` | split and review |
+| 24 | Ingest through the API | Guides / Integrations | ingestion API contract | missing |
+| 25 | Terminology | Getting Started | approved concepts | write after core model |
+| 26 | API overview, auth, and errors | Reference | authored API overview/auth pages | review |
+| 27 | API endpoint groups | Reference | generated OpenAPI pages | generated |
+| 28 | Configuration reference | Reference | committed environment contracts | missing |
+| 29 | Connector capability matrix | Reference | connector specs/tests | missing |
+| 30 | Roles and permissions matrix | Reference | OpenFGA model and domain specs | missing |
+| 31 | MCP tools and resources | Reference | MCP contracts/tests | missing |
+| 32 | Known limitations | Reference | current evidence only | rewrite from evaluation |
+
+Functional coverage and requirement traceability leave public navigation through
+a dedicated later increment. Their canonical evidence remains private in
+domain tests/specs and university deliverables.
+
+## One-Page Checklist
+
+1. Collect code/spec/test/runtime evidence.
+2. Ask the owner focused architecture and audience questions.
+3. Agree on an outline and exclusions.
+4. Draft and review English.
+5. Complete owner teach-back.
+6. Test realistic reader questions and ambiguity.
+7. Draft and review Vietnamese.
+8. Run docs checks, browser/accessibility tests, and publication scans.
+9. PR, merge, immutable build, deploy, and live verification.
+10. Mark exactly one queue item complete and record the next item.
diff --git a/apps/docs/CLAUDE.md b/apps/docs/CLAUDE.md
@@ -1,7 +1,8 @@
 # OrgMemory Docs Guidance
 
 Read the repository root `CLAUDE.md` first, then this file and
-`apps/docs/ARCHITECTURE.md`.
+`apps/docs/ARCHITECTURE.md`. For content work, also read
+`apps/docs/AUTHORING.md`.
 
 - Public prose lives only in `content/docs`; internal engineering documents are
   source evidence, not publication input.
@@ -15,6 +16,9 @@ Read the repository root `CLAUDE.md` first, then this file and
   `/vi/docs/...`. Do not bulk-copy or machine-publish untranslated pages.
 - Vietnamese routes fall back visibly to the reviewed English page until the
   matching `.vi.mdx` exists. A fallback route is not a completed translation.
+- Follow the page queue and co-authoring checkpoints in `AUTHORING.md`. Content
+  work pauses for owner context, outline approval, and teach-back; do not
+  autonomously publish multiple pages.
 - Keep root-folder names and descriptions aligned between `meta.json` and
   `meta.vi.json`; these files define the sidebar documentation switcher.
 - Verify unfamiliar Next.js and Fumadocs APIs against current official

diff --git a/apps/docs/README.md b/apps/docs/README.md
@@ -8,10 +8,35 @@ Run commands from the repository root:
 
 ```powershell
 corepack pnpm install --frozen-lockfile
-corepack pnpm --filter @orgmemory/docs dev
+```
+
+Start the local reader in its own terminal:
+
+```powershell
+corepack pnpm docs:dev
+```
+
+Run verification in another terminal:
+
+```powershell
 corepack pnpm --filter @orgmemory/docs check
 corepack pnpm --filter @orgmemory/docs build
 ```
 
+Open `http://localhost:3000`. The docs application is intentionally
+local-first and independent: it does not require the product API, worker, MCP
+server, database, Keycloak, OpenFGA, or product Compose stack. Dependency
+installation is the only first-run setup; Next.js hot reload handles normal
+page-by-page review.
+
 Set `DOCS_INCLUDE_DRAFTS=true` only for a local or explicitly controlled preview.
 Production uses the public entries in `public-content.manifest.json`.
+
+PowerShell draft preview:
+
+```powershell
+$env:DOCS_INCLUDE_DRAFTS = 'true'
+corepack pnpm docs:dev
+# Press Ctrl+C to stop the preview server before cleaning the parent shell.
+Remove-Item Env:DOCS_INCLUDE_DRAFTS
+```
diff --git a/...content/docs/overview/asset-lifecycle.mdx → ...architecture-security/asset-lifecycle.mdx b/...content/docs/overview/asset-lifecycle.mdx → ...architecture-security/asset-lifecycle.mdx
diff --git a/apps/docs/content/docs/architecture-security/evaluation/traceability.mdx b/apps/docs/content/docs/architecture-security/evaluation/traceability.mdx
@@ -58,7 +58,7 @@ The public software-design view is distributed by reader concern:
 - [Secure retrieval and GraphRAG](/docs/architecture-security/secure-retrieval-graphrag)
   owns candidate filtering, graph contributions, closure recheck, prompts, and
   citations.
-- [Governed Asset lifecycle](/docs/overview/asset-lifecycle) owns reusable
+- [Governed Asset lifecycle](/docs/architecture-security/asset-lifecycle) owns reusable
   capability states, review, exact releases, and delivery.
 
 ## Evidence discipline

diff --git a/apps/docs/content/docs/architecture-security/meta.json b/apps/docs/content/docs/architecture-security/meta.json
@@ -1,10 +1,11 @@
 {
-  "title": "System Design",
+  "title": "Architecture & Security",
   "description": "Understand architecture, data flows, trust boundaries, and evidence.",
   "icon": "Network",
   "root": true,
   "pages": [
     "system-description",
+    "asset-lifecycle",
     "ingestion-lifecycle",
     "authorization",
     "secure-retrieval-graphrag",

diff --git a/apps/docs/content/docs/architecture-security/meta.vi.json b/apps/docs/content/docs/architecture-security/meta.vi.json
@@ -1,10 +1,11 @@
 {
-  "title": "Thiết kế hệ thống",
+  "title": "Kiến trúc & bảo mật",
   "description": "Hiểu kiến trúc, luồng dữ liệu, ranh giới tin cậy và bằng chứng.",
   "icon": "Network",
   "root": true,
   "pages": [
     "system-description",
+    "asset-lifecycle",
     "ingestion-lifecycle",
     "authorization",
     "secure-retrieval-graphrag",

diff --git a/apps/docs/content/docs/developers/meta.json b/apps/docs/content/docs/developers/meta.json
diff --git a/apps/docs/content/docs/developers/meta.vi.json b/apps/docs/content/docs/developers/meta.vi.json
diff --git a/...s/content/docs/overview/core-concepts.mdx → ...nt/docs/getting-started/core-concepts.mdx b/...s/content/docs/overview/core-concepts.mdx → ...nt/docs/getting-started/core-concepts.mdx
diff --git a/apps/docs/content/docs/overview/index.mdx → ...cs/content/docs/getting-started/index.mdx b/apps/docs/content/docs/overview/index.mdx → ...cs/content/docs/getting-started/index.mdx
@@ -71,12 +71,12 @@ It is designed for three related jobs:
   [system description](/docs/architecture-security/system-description), then
   review [coverage](/docs/architecture-security/evaluation/coverage) and
   [limitations](/docs/architecture-security/evaluation/limitations).
-- **Run it locally:** follow the [POC quickstart](/docs/overview/quickstart).
+- **Run it locally:** follow the [POC quickstart](/docs/getting-started/quickstart).
 - **Administer a deployment:** read
-  [identity and permissions](/docs/admins/identity-permissions) and
-  [sources and connections](/docs/admins/sources-connections).
+  [identity and permissions](/docs/guides/administration/identity-permissions) and
+  [sources and connections](/docs/guides/administration/sources-connections).
 - **Integrate an AI client:** use the
-  [Assistant and MCP guide](/docs/developers/assistant-mcp).
+  [Assistant and MCP guide](/docs/guides/integrations/assistant-mcp).
 
 ## Scope boundaries
 

diff --git a/apps/docs/content/docs/getting-started/meta.json b/apps/docs/content/docs/getting-started/meta.json
@@ -0,0 +1,11 @@
+{
+  "title": "Getting Started",
+  "description": "Understand OrgMemory and complete the first governed journey.",
+  "icon": "BookOpen",
+  "root": true,
+  "pages": [
+    "index",
+    "quickstart",
+    "core-concepts"
+  ]
+}
diff --git a/apps/docs/content/docs/getting-started/meta.vi.json b/apps/docs/content/docs/getting-started/meta.vi.json
@@ -0,0 +1,11 @@
+{
+  "title": "Bắt đầu",
+  "description": "Hiểu OrgMemory và hoàn thành hành trình được quản trị đầu tiên.",
+  "icon": "BookOpen",
+  "root": true,
+  "pages": [
+    "index",
+    "quickstart",
+    "core-concepts"
+  ]
+}
diff --git a/...docs/content/docs/overview/quickstart.mdx → ...ntent/docs/getting-started/quickstart.mdx b/...docs/content/docs/overview/quickstart.mdx → ...ntent/docs/getting-started/quickstart.mdx
@@ -96,5 +96,5 @@ publication state are created by the same path used outside the demo.
 | GraphRAG reports unavailable | Configure both chat and embedding routes, or select canonical hybrid explicitly for a provider-free boot. |
 | A document cannot be searched | Confirm it entered through upload/ingestion and reached a published active version. |
 
-Next, read [Core concepts](/docs/overview/core-concepts) before changing
+Next, read [Core concepts](/docs/getting-started/core-concepts) before changing
 authorization or ingestion behavior.
diff --git a/...tent/docs/admins/identity-permissions.mdx → ...s/administration/identity-permissions.mdx b/...tent/docs/admins/identity-permissions.mdx → ...s/administration/identity-permissions.mdx
diff --git a/apps/docs/content/docs/admins/meta.json → ...tent/docs/guides/administration/meta.json b/apps/docs/content/docs/admins/meta.json → ...tent/docs/guides/administration/meta.json
@@ -1,8 +1,7 @@
 {
-  "title": "Govern & Administer",
+  "title": "Administration",
   "description": "Manage identity, permissions, policy, and governed sources.",
   "icon": "ShieldCheck",
-  "root": true,
   "pages": [
     "identity-permissions",
     "sources-connections"

diff --git a/apps/docs/content/docs/admins/meta.vi.json → ...t/docs/guides/administration/meta.vi.json b/apps/docs/content/docs/admins/meta.vi.json → ...t/docs/guides/administration/meta.vi.json
@@ -1,8 +1,7 @@
 {
-  "title": "Quản trị & kiểm soát",
+  "title": "Quản trị",
   "description": "Quản lý danh tính, quyền, chính sách và nguồn dữ liệu.",
   "icon": "ShieldCheck",
-  "root": true,
   "pages": [
     "identity-permissions",
     "sources-connections"

diff --git a/...ntent/docs/admins/sources-connections.mdx → ...es/administration/sources-connections.mdx b/...ntent/docs/admins/sources-connections.mdx → ...es/administration/sources-connections.mdx
diff --git a/apps/docs/content/docs/deployment/meta.json → ...cs/guides/deployment-operations/meta.json b/apps/docs/content/docs/deployment/meta.json → ...cs/guides/deployment-operations/meta.json
@@ -1,8 +1,7 @@
 {
-  "title": "Deploy & Operate",
+  "title": "Deployment & Operations",
   "description": "Deploy, configure, observe, and recover OrgMemory.",
   "icon": "ServerCog",
-  "root": true,
   "pages": [
     "self-hosting"
   ]

diff --git a/...docs/content/docs/deployment/meta.vi.json → ...guides/deployment-operations/meta.vi.json b/...docs/content/docs/deployment/meta.vi.json → ...guides/deployment-operations/meta.vi.json
@@ -2,7 +2,6 @@
   "title": "Triển khai & vận hành",
   "description": "Triển khai, cấu hình, quan sát và khôi phục OrgMemory.",
   "icon": "ServerCog",
-  "root": true,
   "pages": [
     "self-hosting"
   ]

diff --git a/.../content/docs/deployment/self-hosting.mdx → ...es/deployment-operations/self-hosting.mdx b/.../content/docs/deployment/self-hosting.mdx → ...es/deployment-operations/self-hosting.mdx
@@ -46,7 +46,7 @@ docker compose --profile docs up --build docs
 
 The docs health endpoint is `http://localhost:3000/healthz`. Product startup
 and the complete demo flow are covered in the
-[Quickstart](/docs/overview/quickstart).
+[Quickstart](/docs/getting-started/quickstart).
 
 ## Production responsibilities
 

diff --git a/...content/docs/developers/assistant-mcp.mdx → ...ocs/guides/integrations/assistant-mcp.mdx b/...content/docs/developers/assistant-mcp.mdx → ...ocs/guides/integrations/assistant-mcp.mdx