From 0be14541f9fcf286fe9f419b22fd6a46f51aa885 Mon Sep 17 00:00:00 2001 From: kl3inIT Date: Wed, 29 Jul 2026 21:56:44 +0700 Subject: [PATCH 1/2] docs: establish coauthoring program and taxonomy --- apps/docs/ARCHITECTURE.md | 9 +- apps/docs/AUTHORING.md | 164 +++++++++++++++++ apps/docs/CLAUDE.md | 6 +- apps/docs/README.md | 16 +- .../asset-lifecycle.mdx | 0 .../evaluation/traceability.mdx | 2 +- .../docs/architecture-security/meta.json | 3 +- .../docs/architecture-security/meta.vi.json | 3 +- apps/docs/content/docs/developers/meta.json | 10 -- .../docs/content/docs/developers/meta.vi.json | 10 -- .../core-concepts.mdx | 0 .../{overview => getting-started}/index.mdx | 8 +- .../content/docs/getting-started/meta.json | 11 ++ .../content/docs/getting-started/meta.vi.json | 11 ++ .../quickstart.mdx | 2 +- .../administration}/identity-permissions.mdx | 0 .../administration}/meta.json | 3 +- .../administration}/meta.vi.json | 3 +- .../administration}/sources-connections.mdx | 0 .../deployment-operations}/meta.json | 3 +- .../deployment-operations}/meta.vi.json | 1 - .../deployment-operations}/self-hosting.mdx | 2 +- .../integrations}/assistant-mcp.mdx | 0 .../docs/guides/integrations/meta.json | 8 + .../docs/guides/integrations/meta.vi.json | 8 + apps/docs/content/docs/guides/meta.json | 12 ++ apps/docs/content/docs/guides/meta.vi.json | 12 ++ apps/docs/content/docs/meta.json | 7 +- apps/docs/content/docs/meta.vi.json | 7 +- apps/docs/content/docs/overview/meta.json | 12 -- apps/docs/content/docs/overview/meta.vi.json | 12 -- .../api-reference/administration.mdx | 0 .../api-reference/assets.mdx | 0 .../api-reference/assistant.mdx | 0 .../api-reference/authentication.mdx | 0 .../api-reference/index.mdx | 16 +- .../api-reference/knowledge-graph.mdx | 0 .../api-reference/meta.json | 0 .../api-reference/platform.mdx | 0 .../api-reference/search-catalog.mdx | 0 .../api-reference/sources-connections.mdx | 0 apps/docs/content/docs/reference/meta.json | 10 ++ apps/docs/content/docs/reference/meta.vi.json | 10 ++ apps/docs/generated-api.manifest.json | 42 ++--- apps/docs/next.config.mjs | 47 +++++ apps/docs/public-content.manifest.json | 60 +++---- apps/docs/scripts/generate-openapi.ts | 10 +- .../src/app/[lang]/docs/[[...slug]]/page.tsx | 2 +- apps/docs/src/app/global.css | 34 ++-- apps/docs/src/lib/docs-category.ts | 9 +- apps/docs/src/lib/i18n.ts | 2 +- apps/docs/test/e2e/navigation.spec.ts | 73 +++++--- .../design.md | 168 ++++++++++++++++++ .../plan.md | 60 +++++++ .../verification.md | 26 +++ .../2026-07-28-public-docs-portal/design.md | 0 .../2026-07-28-public-docs-portal/plan.md | 14 +- .../verification.md | 33 ++++ docs/roadmap.md | 7 +- package.json | 3 +- 60 files changed, 774 insertions(+), 197 deletions(-) create mode 100644 apps/docs/AUTHORING.md rename apps/docs/content/docs/{overview => architecture-security}/asset-lifecycle.mdx (100%) delete mode 100644 apps/docs/content/docs/developers/meta.json delete mode 100644 apps/docs/content/docs/developers/meta.vi.json rename apps/docs/content/docs/{overview => getting-started}/core-concepts.mdx (100%) rename apps/docs/content/docs/{overview => getting-started}/index.mdx (90%) create mode 100644 apps/docs/content/docs/getting-started/meta.json create mode 100644 apps/docs/content/docs/getting-started/meta.vi.json rename apps/docs/content/docs/{overview => getting-started}/quickstart.mdx (97%) rename apps/docs/content/docs/{admins => guides/administration}/identity-permissions.mdx (100%) rename apps/docs/content/docs/{admins => guides/administration}/meta.json (78%) rename apps/docs/content/docs/{admins => guides/administration}/meta.vi.json (76%) rename apps/docs/content/docs/{admins => guides/administration}/sources-connections.mdx (100%) rename apps/docs/content/docs/{deployment => guides/deployment-operations}/meta.json (74%) rename apps/docs/content/docs/{deployment => guides/deployment-operations}/meta.vi.json (92%) rename apps/docs/content/docs/{deployment => guides/deployment-operations}/self-hosting.mdx (98%) rename apps/docs/content/docs/{developers => guides/integrations}/assistant-mcp.mdx (100%) create mode 100644 apps/docs/content/docs/guides/integrations/meta.json create mode 100644 apps/docs/content/docs/guides/integrations/meta.vi.json create mode 100644 apps/docs/content/docs/guides/meta.json create mode 100644 apps/docs/content/docs/guides/meta.vi.json delete mode 100644 apps/docs/content/docs/overview/meta.json delete mode 100644 apps/docs/content/docs/overview/meta.vi.json rename apps/docs/content/docs/{developers => reference}/api-reference/administration.mdx (100%) rename apps/docs/content/docs/{developers => reference}/api-reference/assets.mdx (100%) rename apps/docs/content/docs/{developers => reference}/api-reference/assistant.mdx (100%) rename apps/docs/content/docs/{developers => reference}/api-reference/authentication.mdx (100%) rename apps/docs/content/docs/{developers => reference}/api-reference/index.mdx (56%) rename apps/docs/content/docs/{developers => reference}/api-reference/knowledge-graph.mdx (100%) rename apps/docs/content/docs/{developers => reference}/api-reference/meta.json (100%) rename apps/docs/content/docs/{developers => reference}/api-reference/platform.mdx (100%) rename apps/docs/content/docs/{developers => reference}/api-reference/search-catalog.mdx (100%) rename apps/docs/content/docs/{developers => reference}/api-reference/sources-connections.mdx (100%) create mode 100644 apps/docs/content/docs/reference/meta.json create mode 100644 apps/docs/content/docs/reference/meta.vi.json create mode 100644 docs/increments/active/2026-07-29-public-docs-coauthoring/design.md create mode 100644 docs/increments/active/2026-07-29-public-docs-coauthoring/plan.md create mode 100644 docs/increments/active/2026-07-29-public-docs-coauthoring/verification.md rename docs/increments/{active => completed}/2026-07-28-public-docs-portal/design.md (100%) rename docs/increments/{active => completed}/2026-07-28-public-docs-portal/plan.md (96%) rename docs/increments/{active => completed}/2026-07-28-public-docs-portal/verification.md (90%) diff --git a/apps/docs/ARCHITECTURE.md b/apps/docs/ARCHITECTURE.md index 9c5949d0..9fcb3a46 100644 --- 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 new file mode 100644 index 00000000..3688c163 --- /dev/null +++ b/apps/docs/AUTHORING.md @@ -0,0 +1,164 @@ +# 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 +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 index fb0cc06b..4f2013d2 100644 --- 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 index ae1e1fa4..256d297a 100644 --- a/apps/docs/README.md +++ b/apps/docs/README.md @@ -8,10 +8,24 @@ Run commands from the repository root: ```powershell corepack pnpm install --frozen-lockfile -corepack pnpm --filter @orgmemory/docs dev +corepack pnpm docs:dev 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 +Remove-Item Env:DOCS_INCLUDE_DRAFTS +``` diff --git a/apps/docs/content/docs/overview/asset-lifecycle.mdx b/apps/docs/content/docs/architecture-security/asset-lifecycle.mdx similarity index 100% rename from apps/docs/content/docs/overview/asset-lifecycle.mdx rename to apps/docs/content/docs/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 index 3c6965d8..a4b802fa 100644 --- 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 index 6c88eeab..e1427cae 100644 --- 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 index 9863954a..8d98089e 100644 --- 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 deleted file mode 100644 index 979dfd9f..00000000 --- a/apps/docs/content/docs/developers/meta.json +++ /dev/null @@ -1,10 +0,0 @@ -{ - "title": "Build & Integrate", - "description": "Develop against supported API, MCP, and product contracts.", - "icon": "Braces", - "root": true, - "pages": [ - "assistant-mcp", - "api-reference" - ] -} diff --git a/apps/docs/content/docs/developers/meta.vi.json b/apps/docs/content/docs/developers/meta.vi.json deleted file mode 100644 index 3959063c..00000000 --- a/apps/docs/content/docs/developers/meta.vi.json +++ /dev/null @@ -1,10 +0,0 @@ -{ - "title": "Phát triển & tích hợp", - "description": "Phát triển dựa trên API, MCP và các hợp đồng được hỗ trợ.", - "icon": "Braces", - "root": true, - "pages": [ - "assistant-mcp", - "api-reference" - ] -} diff --git a/apps/docs/content/docs/overview/core-concepts.mdx b/apps/docs/content/docs/getting-started/core-concepts.mdx similarity index 100% rename from apps/docs/content/docs/overview/core-concepts.mdx rename to apps/docs/content/docs/getting-started/core-concepts.mdx diff --git a/apps/docs/content/docs/overview/index.mdx b/apps/docs/content/docs/getting-started/index.mdx similarity index 90% rename from apps/docs/content/docs/overview/index.mdx rename to apps/docs/content/docs/getting-started/index.mdx index 7ee1172b..ecd96f41 100644 --- a/apps/docs/content/docs/overview/index.mdx +++ b/apps/docs/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 new file mode 100644 index 00000000..723691fd --- /dev/null +++ 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 new file mode 100644 index 00000000..cfa224bc --- /dev/null +++ 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/apps/docs/content/docs/overview/quickstart.mdx b/apps/docs/content/docs/getting-started/quickstart.mdx similarity index 97% rename from apps/docs/content/docs/overview/quickstart.mdx rename to apps/docs/content/docs/getting-started/quickstart.mdx index a8a8063d..d9555f30 100644 --- a/apps/docs/content/docs/overview/quickstart.mdx +++ b/apps/docs/content/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/apps/docs/content/docs/admins/identity-permissions.mdx b/apps/docs/content/docs/guides/administration/identity-permissions.mdx similarity index 100% rename from apps/docs/content/docs/admins/identity-permissions.mdx rename to apps/docs/content/docs/guides/administration/identity-permissions.mdx diff --git a/apps/docs/content/docs/admins/meta.json b/apps/docs/content/docs/guides/administration/meta.json similarity index 78% rename from apps/docs/content/docs/admins/meta.json rename to apps/docs/content/docs/guides/administration/meta.json index 217991f1..441988ca 100644 --- a/apps/docs/content/docs/admins/meta.json +++ b/apps/docs/content/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 b/apps/docs/content/docs/guides/administration/meta.vi.json similarity index 76% rename from apps/docs/content/docs/admins/meta.vi.json rename to apps/docs/content/docs/guides/administration/meta.vi.json index 9ef4941d..cfe3d547 100644 --- a/apps/docs/content/docs/admins/meta.vi.json +++ b/apps/docs/content/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/apps/docs/content/docs/admins/sources-connections.mdx b/apps/docs/content/docs/guides/administration/sources-connections.mdx similarity index 100% rename from apps/docs/content/docs/admins/sources-connections.mdx rename to apps/docs/content/docs/guides/administration/sources-connections.mdx diff --git a/apps/docs/content/docs/deployment/meta.json b/apps/docs/content/docs/guides/deployment-operations/meta.json similarity index 74% rename from apps/docs/content/docs/deployment/meta.json rename to apps/docs/content/docs/guides/deployment-operations/meta.json index 4276d43a..70b1e3e7 100644 --- a/apps/docs/content/docs/deployment/meta.json +++ b/apps/docs/content/docs/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/apps/docs/content/docs/deployment/meta.vi.json b/apps/docs/content/docs/guides/deployment-operations/meta.vi.json similarity index 92% rename from apps/docs/content/docs/deployment/meta.vi.json rename to apps/docs/content/docs/guides/deployment-operations/meta.vi.json index 5efb2b66..3a6c29de 100644 --- a/apps/docs/content/docs/deployment/meta.vi.json +++ b/apps/docs/content/docs/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/apps/docs/content/docs/deployment/self-hosting.mdx b/apps/docs/content/docs/guides/deployment-operations/self-hosting.mdx similarity index 98% rename from apps/docs/content/docs/deployment/self-hosting.mdx rename to apps/docs/content/docs/guides/deployment-operations/self-hosting.mdx index 5c21f26a..d39d8f5e 100644 --- a/apps/docs/content/docs/deployment/self-hosting.mdx +++ b/apps/docs/content/docs/guides/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/apps/docs/content/docs/developers/assistant-mcp.mdx b/apps/docs/content/docs/guides/integrations/assistant-mcp.mdx similarity index 100% rename from apps/docs/content/docs/developers/assistant-mcp.mdx rename to apps/docs/content/docs/guides/integrations/assistant-mcp.mdx diff --git a/apps/docs/content/docs/guides/integrations/meta.json b/apps/docs/content/docs/guides/integrations/meta.json new file mode 100644 index 00000000..e277d590 --- /dev/null +++ b/apps/docs/content/docs/guides/integrations/meta.json @@ -0,0 +1,8 @@ +{ + "title": "Integrations", + "description": "Connect supported clients and delivery interfaces.", + "icon": "Cable", + "pages": [ + "assistant-mcp" + ] +} diff --git a/apps/docs/content/docs/guides/integrations/meta.vi.json b/apps/docs/content/docs/guides/integrations/meta.vi.json new file mode 100644 index 00000000..a4b88178 --- /dev/null +++ b/apps/docs/content/docs/guides/integrations/meta.vi.json @@ -0,0 +1,8 @@ +{ + "title": "Tích hợp", + "description": "Kết nối các client và giao diện phân phối được hỗ trợ.", + "icon": "Cable", + "pages": [ + "assistant-mcp" + ] +} diff --git a/apps/docs/content/docs/guides/meta.json b/apps/docs/content/docs/guides/meta.json new file mode 100644 index 00000000..7ed05929 --- /dev/null +++ b/apps/docs/content/docs/guides/meta.json @@ -0,0 +1,12 @@ +{ + "title": "Guides", + "description": "Complete product, administration, operations, and integration tasks.", + "icon": "ListChecks", + "root": true, + "pagesIndex": "administration/identity-permissions", + "pages": [ + "administration", + "deployment-operations", + "integrations" + ] +} diff --git a/apps/docs/content/docs/guides/meta.vi.json b/apps/docs/content/docs/guides/meta.vi.json new file mode 100644 index 00000000..695496e6 --- /dev/null +++ b/apps/docs/content/docs/guides/meta.vi.json @@ -0,0 +1,12 @@ +{ + "title": "Hướng dẫn", + "description": "Thực hiện các tác vụ sản phẩm, quản trị, vận hành và tích hợp.", + "icon": "ListChecks", + "root": true, + "pagesIndex": "administration/identity-permissions", + "pages": [ + "administration", + "deployment-operations", + "integrations" + ] +} diff --git a/apps/docs/content/docs/meta.json b/apps/docs/content/docs/meta.json index c35c3992..2b2dcf2e 100644 --- a/apps/docs/content/docs/meta.json +++ b/apps/docs/content/docs/meta.json @@ -1,10 +1,9 @@ { "title": "OrgMemory", "pages": [ - "overview", + "getting-started", + "guides", "architecture-security", - "deployment", - "admins", - "developers" + "reference" ] } diff --git a/apps/docs/content/docs/meta.vi.json b/apps/docs/content/docs/meta.vi.json index c35c3992..2b2dcf2e 100644 --- a/apps/docs/content/docs/meta.vi.json +++ b/apps/docs/content/docs/meta.vi.json @@ -1,10 +1,9 @@ { "title": "OrgMemory", "pages": [ - "overview", + "getting-started", + "guides", "architecture-security", - "deployment", - "admins", - "developers" + "reference" ] } diff --git a/apps/docs/content/docs/overview/meta.json b/apps/docs/content/docs/overview/meta.json deleted file mode 100644 index e57bf357..00000000 --- a/apps/docs/content/docs/overview/meta.json +++ /dev/null @@ -1,12 +0,0 @@ -{ - "title": "Start Here", - "description": "Build the mental model before reading implementation details.", - "icon": "BookOpen", - "root": true, - "pages": [ - "index", - "quickstart", - "core-concepts", - "asset-lifecycle" - ] -} diff --git a/apps/docs/content/docs/overview/meta.vi.json b/apps/docs/content/docs/overview/meta.vi.json deleted file mode 100644 index e2332512..00000000 --- a/apps/docs/content/docs/overview/meta.vi.json +++ /dev/null @@ -1,12 +0,0 @@ -{ - "title": "Bắt đầu", - "description": "Nắm mô hình tư duy trước khi đọc chi tiết triển khai.", - "icon": "BookOpen", - "root": true, - "pages": [ - "index", - "quickstart", - "core-concepts", - "asset-lifecycle" - ] -} diff --git a/apps/docs/content/docs/developers/api-reference/administration.mdx b/apps/docs/content/docs/reference/api-reference/administration.mdx similarity index 100% rename from apps/docs/content/docs/developers/api-reference/administration.mdx rename to apps/docs/content/docs/reference/api-reference/administration.mdx diff --git a/apps/docs/content/docs/developers/api-reference/assets.mdx b/apps/docs/content/docs/reference/api-reference/assets.mdx similarity index 100% rename from apps/docs/content/docs/developers/api-reference/assets.mdx rename to apps/docs/content/docs/reference/api-reference/assets.mdx diff --git a/apps/docs/content/docs/developers/api-reference/assistant.mdx b/apps/docs/content/docs/reference/api-reference/assistant.mdx similarity index 100% rename from apps/docs/content/docs/developers/api-reference/assistant.mdx rename to apps/docs/content/docs/reference/api-reference/assistant.mdx diff --git a/apps/docs/content/docs/developers/api-reference/authentication.mdx b/apps/docs/content/docs/reference/api-reference/authentication.mdx similarity index 100% rename from apps/docs/content/docs/developers/api-reference/authentication.mdx rename to apps/docs/content/docs/reference/api-reference/authentication.mdx diff --git a/apps/docs/content/docs/developers/api-reference/index.mdx b/apps/docs/content/docs/reference/api-reference/index.mdx similarity index 56% rename from apps/docs/content/docs/developers/api-reference/index.mdx rename to apps/docs/content/docs/reference/api-reference/index.mdx index 75f9cbf1..ac589143 100644 --- a/apps/docs/content/docs/developers/api-reference/index.mdx +++ b/apps/docs/content/docs/reference/api-reference/index.mdx @@ -18,20 +18,20 @@ OrgMemory publishes a generated reference from the repository's committed OpenAP ## Before you integrate -1. Read [Authentication and errors](/docs/developers/api-reference/authentication) for browser-session, CSRF, authorization, and error-handling expectations. +1. Read [Authentication and errors](/docs/reference/api-reference/authentication) for browser-session, CSRF, authorization, and error-handling expectations. 2. Choose the endpoint group below. 3. Confirm the operation against the exact OrgMemory release you deploy. 4. Exercise the flow in a non-production environment with a least-privilege identity. ## Endpoint groups -- [Administration](/docs/developers/api-reference/administration) — identity, roles, permissions, and organization controls. -- [Sources and connections](/docs/developers/api-reference/sources-connections) — source registration, credentials, crawl control, and access mapping. -- [Assets](/docs/developers/api-reference/assets) — governed assets, releases, delivery, and lifecycle operations. -- [Assistant](/docs/developers/api-reference/assistant) — conversations and permission-aware assistant tools. -- [Knowledge graph](/docs/developers/api-reference/knowledge-graph) — graph indexing, exploration, curation, and export. -- [Search and catalog](/docs/developers/api-reference/search-catalog) — retrieval, catalog browsing, and citation content. -- [Platform](/docs/developers/api-reference/platform) — session, organization context, health, and visible spaces. +- [Administration](/docs/reference/api-reference/administration) — identity, roles, permissions, and organization controls. +- [Sources and connections](/docs/reference/api-reference/sources-connections) — source registration, credentials, crawl control, and access mapping. +- [Assets](/docs/reference/api-reference/assets) — governed assets, releases, delivery, and lifecycle operations. +- [Assistant](/docs/reference/api-reference/assistant) — conversations and permission-aware assistant tools. +- [Knowledge graph](/docs/reference/api-reference/knowledge-graph) — graph indexing, exploration, curation, and export. +- [Search and catalog](/docs/reference/api-reference/search-catalog) — retrieval, catalog browsing, and citation content. +- [Platform](/docs/reference/api-reference/platform) — session, organization context, health, and visible spaces. ## Generated-reference safety diff --git a/apps/docs/content/docs/developers/api-reference/knowledge-graph.mdx b/apps/docs/content/docs/reference/api-reference/knowledge-graph.mdx similarity index 100% rename from apps/docs/content/docs/developers/api-reference/knowledge-graph.mdx rename to apps/docs/content/docs/reference/api-reference/knowledge-graph.mdx diff --git a/apps/docs/content/docs/developers/api-reference/meta.json b/apps/docs/content/docs/reference/api-reference/meta.json similarity index 100% rename from apps/docs/content/docs/developers/api-reference/meta.json rename to apps/docs/content/docs/reference/api-reference/meta.json diff --git a/apps/docs/content/docs/developers/api-reference/platform.mdx b/apps/docs/content/docs/reference/api-reference/platform.mdx similarity index 100% rename from apps/docs/content/docs/developers/api-reference/platform.mdx rename to apps/docs/content/docs/reference/api-reference/platform.mdx diff --git a/apps/docs/content/docs/developers/api-reference/search-catalog.mdx b/apps/docs/content/docs/reference/api-reference/search-catalog.mdx similarity index 100% rename from apps/docs/content/docs/developers/api-reference/search-catalog.mdx rename to apps/docs/content/docs/reference/api-reference/search-catalog.mdx diff --git a/apps/docs/content/docs/developers/api-reference/sources-connections.mdx b/apps/docs/content/docs/reference/api-reference/sources-connections.mdx similarity index 100% rename from apps/docs/content/docs/developers/api-reference/sources-connections.mdx rename to apps/docs/content/docs/reference/api-reference/sources-connections.mdx diff --git a/apps/docs/content/docs/reference/meta.json b/apps/docs/content/docs/reference/meta.json new file mode 100644 index 00000000..27cafb27 --- /dev/null +++ b/apps/docs/content/docs/reference/meta.json @@ -0,0 +1,10 @@ +{ + "title": "Reference", + "description": "Look up exact API, configuration, and product contracts.", + "icon": "Braces", + "root": true, + "pagesIndex": "api-reference/index", + "pages": [ + "api-reference" + ] +} diff --git a/apps/docs/content/docs/reference/meta.vi.json b/apps/docs/content/docs/reference/meta.vi.json new file mode 100644 index 00000000..cf878ae7 --- /dev/null +++ b/apps/docs/content/docs/reference/meta.vi.json @@ -0,0 +1,10 @@ +{ + "title": "Tham chiếu", + "description": "Tra cứu chính xác API, cấu hình và các hợp đồng sản phẩm.", + "icon": "Braces", + "root": true, + "pagesIndex": "api-reference/index", + "pages": [ + "api-reference" + ] +} diff --git a/apps/docs/generated-api.manifest.json b/apps/docs/generated-api.manifest.json index f1e81c2b..d3fe117c 100644 --- a/apps/docs/generated-api.manifest.json +++ b/apps/docs/generated-api.manifest.json @@ -2,57 +2,57 @@ "schemaVersion": 1, "entries": [ { - "route": "/docs/developers/api-reference/administration", - "content": "content/docs/developers/api-reference/administration.mdx", - "area": "developers", + "route": "/docs/reference/api-reference/administration", + "content": "content/docs/reference/api-reference/administration.mdx", + "area": "reference", "order": 40, "status": "public", "reviewOwner": "identity-and-authorization-maintainers" }, { - "route": "/docs/developers/api-reference/sources-connections", - "content": "content/docs/developers/api-reference/sources-connections.mdx", - "area": "developers", + "route": "/docs/reference/api-reference/sources-connections", + "content": "content/docs/reference/api-reference/sources-connections.mdx", + "area": "reference", "order": 50, "status": "public", "reviewOwner": "connector-maintainers" }, { - "route": "/docs/developers/api-reference/assets", - "content": "content/docs/developers/api-reference/assets.mdx", - "area": "developers", + "route": "/docs/reference/api-reference/assets", + "content": "content/docs/reference/api-reference/assets.mdx", + "area": "reference", "order": 60, "status": "public", "reviewOwner": "asset-registry-maintainers" }, { - "route": "/docs/developers/api-reference/assistant", - "content": "content/docs/developers/api-reference/assistant.mdx", - "area": "developers", + "route": "/docs/reference/api-reference/assistant", + "content": "content/docs/reference/api-reference/assistant.mdx", + "area": "reference", "order": 70, "status": "public", "reviewOwner": "assistant-and-mcp-maintainers" }, { - "route": "/docs/developers/api-reference/knowledge-graph", - "content": "content/docs/developers/api-reference/knowledge-graph.mdx", - "area": "developers", + "route": "/docs/reference/api-reference/knowledge-graph", + "content": "content/docs/reference/api-reference/knowledge-graph.mdx", + "area": "reference", "order": 80, "status": "public", "reviewOwner": "retrieval-maintainers" }, { - "route": "/docs/developers/api-reference/search-catalog", - "content": "content/docs/developers/api-reference/search-catalog.mdx", - "area": "developers", + "route": "/docs/reference/api-reference/search-catalog", + "content": "content/docs/reference/api-reference/search-catalog.mdx", + "area": "reference", "order": 90, "status": "public", "reviewOwner": "retrieval-maintainers" }, { - "route": "/docs/developers/api-reference/platform", - "content": "content/docs/developers/api-reference/platform.mdx", - "area": "developers", + "route": "/docs/reference/api-reference/platform", + "content": "content/docs/reference/api-reference/platform.mdx", + "area": "reference", "order": 100, "status": "public", "reviewOwner": "api-maintainers" diff --git a/apps/docs/next.config.mjs b/apps/docs/next.config.mjs index 93c5decd..2b8da729 100644 --- a/apps/docs/next.config.mjs +++ b/apps/docs/next.config.mjs @@ -3,12 +3,59 @@ import { fileURLToPath } from 'node:url'; const withMDX = createMDX(); const repositoryRoot = fileURLToPath(new URL('../..', import.meta.url)); +const movedDocsPages = [ + ['/docs/overview', '/docs/getting-started'], + ['/docs/overview/quickstart', '/docs/getting-started/quickstart'], + ['/docs/overview/core-concepts', '/docs/getting-started/core-concepts'], + ['/docs/overview/asset-lifecycle', '/docs/architecture-security/asset-lifecycle'], + ['/docs/admins', '/docs/guides/administration/identity-permissions'], + [ + '/docs/admins/identity-permissions', + '/docs/guides/administration/identity-permissions', + ], + [ + '/docs/admins/sources-connections', + '/docs/guides/administration/sources-connections', + ], + ['/docs/deployment', '/docs/guides/deployment-operations/self-hosting'], + ['/docs/deployment/self-hosting', '/docs/guides/deployment-operations/self-hosting'], + ['/docs/developers', '/docs/guides/integrations/assistant-mcp'], + ['/docs/developers/assistant-mcp', '/docs/guides/integrations/assistant-mcp'], + ['/docs/developers/api-reference', '/docs/reference/api-reference'], +]; + +function movedPageRedirects() { + return movedDocsPages.flatMap(([source, destination]) => + ['', '/vi'].flatMap((locale) => + ['', '.md'].map((extension) => ({ + source: `${locale}${source}${extension}`, + destination: `${locale}${destination}${extension}`, + permanent: true, + })), + ), + ); +} /** @type {import('next').NextConfig} */ const config = { output: 'standalone', outputFileTracingRoot: repositoryRoot, reactStrictMode: true, + async redirects() { + return [ + ...movedPageRedirects(), + { + source: '/docs/developers/api-reference/:path*', + destination: '/docs/reference/api-reference/:path*', + permanent: true, + }, + { + source: '/vi/docs/developers/api-reference/:path*', + destination: '/vi/docs/reference/api-reference/:path*', + permanent: true, + }, + ]; + }, async headers() { return [ { diff --git a/apps/docs/public-content.manifest.json b/apps/docs/public-content.manifest.json index a5b474b3..cc45ab94 100644 --- a/apps/docs/public-content.manifest.json +++ b/apps/docs/public-content.manifest.json @@ -2,81 +2,81 @@ "schemaVersion": 1, "entries": [ { - "route": "/docs/overview", - "content": "content/docs/overview/index.mdx", - "area": "overview", + "route": "/docs/getting-started", + "content": "content/docs/getting-started/index.mdx", + "area": "getting-started", "order": 10, "status": "public", "reviewOwner": "product-and-documentation" }, { - "route": "/docs/overview/quickstart", - "content": "content/docs/overview/quickstart.mdx", - "area": "overview", + "route": "/docs/getting-started/quickstart", + "content": "content/docs/getting-started/quickstart.mdx", + "area": "getting-started", "order": 20, "status": "public", "reviewOwner": "developer-experience" }, { - "route": "/docs/overview/core-concepts", - "content": "content/docs/overview/core-concepts.mdx", - "area": "overview", + "route": "/docs/getting-started/core-concepts", + "content": "content/docs/getting-started/core-concepts.mdx", + "area": "getting-started", "order": 30, "status": "public", "reviewOwner": "product-and-documentation" }, { - "route": "/docs/overview/asset-lifecycle", - "content": "content/docs/overview/asset-lifecycle.mdx", - "area": "overview", + "route": "/docs/architecture-security/asset-lifecycle", + "content": "content/docs/architecture-security/asset-lifecycle.mdx", + "area": "architecture-security", "order": 40, "status": "public", "reviewOwner": "asset-registry-maintainers" }, { - "route": "/docs/deployment/self-hosting", - "content": "content/docs/deployment/self-hosting.mdx", - "area": "deployment", + "route": "/docs/guides/deployment-operations/self-hosting", + "content": "content/docs/guides/deployment-operations/self-hosting.mdx", + "area": "guides", "order": 10, "status": "public", "reviewOwner": "operations-maintainers" }, { - "route": "/docs/admins/identity-permissions", - "content": "content/docs/admins/identity-permissions.mdx", - "area": "admins", + "route": "/docs/guides/administration/identity-permissions", + "content": "content/docs/guides/administration/identity-permissions.mdx", + "area": "guides", "order": 10, "status": "public", "reviewOwner": "identity-and-authorization-maintainers" }, { - "route": "/docs/admins/sources-connections", - "content": "content/docs/admins/sources-connections.mdx", - "area": "admins", + "route": "/docs/guides/administration/sources-connections", + "content": "content/docs/guides/administration/sources-connections.mdx", + "area": "guides", "order": 20, "status": "public", "reviewOwner": "connector-maintainers" }, { - "route": "/docs/developers/assistant-mcp", - "content": "content/docs/developers/assistant-mcp.mdx", - "area": "developers", + "route": "/docs/guides/integrations/assistant-mcp", + "content": "content/docs/guides/integrations/assistant-mcp.mdx", + "area": "guides", "order": 10, "status": "public", "reviewOwner": "assistant-and-mcp-maintainers" }, { - "route": "/docs/developers/api-reference", - "content": "content/docs/developers/api-reference/index.mdx", - "area": "developers", + "route": "/docs/reference/api-reference", + "content": "content/docs/reference/api-reference/index.mdx", + "area": "reference", "order": 20, "status": "public", "reviewOwner": "developer-experience" }, { - "route": "/docs/developers/api-reference/authentication", - "content": "content/docs/developers/api-reference/authentication.mdx", - "area": "developers", + "route": "/docs/reference/api-reference/authentication", + "content": "content/docs/reference/api-reference/authentication.mdx", + "area": "reference", "order": 30, "status": "public", "reviewOwner": "identity-and-authorization-maintainers" diff --git a/apps/docs/scripts/generate-openapi.ts b/apps/docs/scripts/generate-openapi.ts index 03f777c0..afc055e2 100644 --- a/apps/docs/scripts/generate-openapi.ts +++ b/apps/docs/scripts/generate-openapi.ts @@ -12,7 +12,7 @@ const repositoryRoot = path.resolve(docsRoot, '..', '..'); const contractPath = path.join(repositoryRoot, 'contracts', 'openapi.json'); const publicContractPath = path.join(docsRoot, 'generated', 'openapi.public.json'); const generatedManifestPath = path.join(docsRoot, 'generated-api.manifest.json'); -const contentRoot = path.join(docsRoot, 'content', 'docs', 'developers', 'api-reference'); +const contentRoot = path.join(docsRoot, 'content', 'docs', 'reference', 'api-reference'); const checkOnly = process.argv.includes('--check'); const schemaId = 'orgmemory-public'; const generatedBanner = @@ -173,9 +173,9 @@ function expectedManifest(files: { path: string; content: string }[]) { const domain = domains.find((candidate) => candidate.slug === slug); if (!domain) fail(`Unexpected generated OpenAPI page: ${file.path}`); return { - route: `/docs/developers/api-reference/${slug}`, - content: `content/docs/developers/api-reference/${file.path}`, - area: 'developers', + route: `/docs/reference/api-reference/${slug}`, + content: `content/docs/reference/api-reference/${file.path}`, + area: 'reference', order: 40 + index * 10, status: 'public', reviewOwner: domain.owner, @@ -242,7 +242,7 @@ if (checkOnly) { for (const entry of previous.entries ?? []) { if ( typeof entry.content !== 'string' || - !entry.content.startsWith('content/docs/developers/api-reference/') + !entry.content.startsWith('content/docs/reference/api-reference/') ) { continue; } diff --git a/apps/docs/src/app/[lang]/docs/[[...slug]]/page.tsx b/apps/docs/src/app/[lang]/docs/[[...slug]]/page.tsx index d1e5d2a1..05deb7f0 100644 --- a/apps/docs/src/app/[lang]/docs/[[...slug]]/page.tsx +++ b/apps/docs/src/app/[lang]/docs/[[...slug]]/page.tsx @@ -91,7 +91,7 @@ export async function generateMetadata( ): Promise { const params = await props.params; if (!isDocsLanguage(params.lang)) notFound(); - const slug = params.slug?.length ? params.slug : ['overview']; + const slug = params.slug?.length ? params.slug : ['getting-started']; const page = source.getPage(slug, params.lang); if (!page) notFound(); diff --git a/apps/docs/src/app/global.css b/apps/docs/src/app/global.css index 9f8f567b..68524d63 100644 --- a/apps/docs/src/app/global.css +++ b/apps/docs/src/app/global.css @@ -12,40 +12,34 @@ html { :root { --color-fd-muted-foreground: hsl(0, 0%, 41%); - --docs-overview-color: hsl(42, 95%, 27%); + --docs-getting-started-color: hsl(42, 95%, 27%); + --docs-guides-color: hsl(158, 75%, 28%); --docs-architecture-security-color: hsl(199, 89%, 34%); - --docs-deployment-color: hsl(24, 95%, 37%); - --docs-admins-color: hsl(158, 75%, 28%); - --docs-developers-color: hsl(258, 70%, 48%); + --docs-reference-color: hsl(258, 70%, 48%); } .dark { --color-fd-muted-foreground: hsl(0, 0%, 75%); - --docs-overview-color: #fcd34d; + --docs-getting-started-color: #fcd34d; + --docs-guides-color: #6ee7b7; --docs-architecture-security-color: #67e8f9; - --docs-deployment-color: #fdba74; - --docs-admins-color: #6ee7b7; - --docs-developers-color: #c4b5fd; + --docs-reference-color: #c4b5fd; } -.overview { - --color-fd-primary: var(--docs-overview-color); +.getting-started { + --color-fd-primary: var(--docs-getting-started-color); } -.architecture-security { - --color-fd-primary: var(--docs-architecture-security-color); -} - -.deployment { - --color-fd-primary: var(--docs-deployment-color); +.guides { + --color-fd-primary: var(--docs-guides-color); } -.admins { - --color-fd-primary: var(--docs-admins-color); +.architecture-security { + --color-fd-primary: var(--docs-architecture-security-color); } -.developers { - --color-fd-primary: var(--docs-developers-color); +.reference { + --color-fd-primary: var(--docs-reference-color); } header span.truncate { diff --git a/apps/docs/src/lib/docs-category.ts b/apps/docs/src/lib/docs-category.ts index 8d6bf875..497320a5 100644 --- a/apps/docs/src/lib/docs-category.ts +++ b/apps/docs/src/lib/docs-category.ts @@ -1,9 +1,8 @@ export const docsCategories = [ - 'overview', + 'getting-started', + 'guides', 'architecture-security', - 'deployment', - 'admins', - 'developers', + 'reference', ] as const; export type DocsCategory = (typeof docsCategories)[number]; @@ -14,7 +13,7 @@ export function getDocsCategory(path?: string | string[]): DocsCategory { const segments = Array.isArray(path) ? path : path?.split('/'); const category = segments?.find((segment) => docsCategorySet.has(segment)); - return (category as DocsCategory | undefined) ?? 'overview'; + return (category as DocsCategory | undefined) ?? 'getting-started'; } export function getDocsCategoryColor(category: DocsCategory) { diff --git a/apps/docs/src/lib/i18n.ts b/apps/docs/src/lib/i18n.ts index 47e8ebe8..1e5bee79 100644 --- a/apps/docs/src/lib/i18n.ts +++ b/apps/docs/src/lib/i18n.ts @@ -20,7 +20,7 @@ export function withLocale(pathname: string, language: DocsLanguage): string { } export function docsHome(language: DocsLanguage): string { - return withLocale('/docs/overview', language); + return withLocale('/docs/getting-started', language); } export const translations = i18n diff --git a/apps/docs/test/e2e/navigation.spec.ts b/apps/docs/test/e2e/navigation.spec.ts index 6a2613d1..6204cbe1 100644 --- a/apps/docs/test/e2e/navigation.spec.ts +++ b/apps/docs/test/e2e/navigation.spec.ts @@ -15,7 +15,7 @@ const publicRoutes = [...authoredManifest.entries, ...generatedManifest.entries] test('site root enters the technical documentation directly', async ({ page }) => { await page.goto('/'); - await expect(page).toHaveURL(/\/docs\/overview$/); + await expect(page).toHaveURL(/\/docs\/getting-started$/); await expect( page.getByRole('heading', { level: 1, name: 'Welcome to OrgMemory' }), ).toBeVisible(); @@ -39,13 +39,12 @@ test('public corpus exposes the section switcher and focused page tree', async ( if (testInfo.project.name === 'mobile-chromium') { await page.getByRole('button', { name: 'Open Sidebar' }).click(); } - await page.getByRole('button', { name: /System Design/ }).first().click(); + await page.getByRole('button', { name: /Architecture & Security/ }).first().click(); for (const section of [ - 'Start Here', - 'System Design', - 'Deploy & Operate', - 'Govern & Administer', - 'Build & Integrate', + 'Getting Started', + 'Guides', + 'Architecture & Security', + 'Reference', ]) { await expect(page.getByText(section, { exact: true }).last()).toBeVisible(); } @@ -56,11 +55,10 @@ test('public corpus exposes the section switcher and focused page tree', async ( test('category visual identity follows the active root and locale', async ({ page }) => { const categories = { - overview: '/docs/overview', + 'getting-started': '/docs/getting-started', + guides: '/docs/guides/administration/identity-permissions', 'architecture-security': '/docs/architecture-security/system-description', - deployment: '/docs/deployment/self-hosting', - admins: '/docs/admins/identity-permissions', - developers: '/docs/developers/assistant-mcp', + reference: '/docs/reference/api-reference', } as const; const colors = new Map(); @@ -87,7 +85,7 @@ test('category visual identity follows the active root and locale', async ({ pag test('Vietnamese shell is localized while untranslated pages fall back explicitly', async ({ page, }, testInfo) => { - await page.goto('/vi/docs/overview'); + await page.goto('/vi/docs/getting-started'); await expect(page.locator('html')).toHaveAttribute('lang', 'vi'); await expect( @@ -103,10 +101,9 @@ test('Vietnamese shell is localized while untranslated pages fall back explicitl await page.getByRole('button', { name: /Bắt đầu/ }).first().click(); for (const section of [ 'Bắt đầu', - 'Thiết kế hệ thống', - 'Triển khai & vận hành', - 'Quản trị & kiểm soát', - 'Phát triển & tích hợp', + 'Hướng dẫn', + 'Kiến trúc & bảo mật', + 'Tham chiếu', ]) { await expect(page.getByText(section, { exact: true }).last()).toBeVisible(); } @@ -114,20 +111,48 @@ test('Vietnamese shell is localized while untranslated pages fall back explicitl await page.getByRole('button', { name: 'Chọn ngôn ngữ' }).first().click(); await page.getByRole('button', { name: 'English', exact: true }).last().click(); - await expect(page).toHaveURL(/\/docs\/overview$/); + await expect(page).toHaveURL(/\/docs\/getting-started$/); await expect(page.locator('html')).toHaveAttribute('lang', 'en'); }); -test('docs root redirects to the published overview', async ({ page }) => { +test('docs root redirects to Getting Started', async ({ page }) => { await page.goto('/docs'); - await expect(page).toHaveURL(/\/docs\/overview$/); + await expect(page).toHaveURL(/\/docs\/getting-started$/); await expect( page.getByRole('heading', { level: 1, name: 'Welcome to OrgMemory' }), ).toBeVisible(); }); +test('legacy docs URLs permanently redirect to the new taxonomy', async ({ + request, +}, testInfo) => { + test.skip(testInfo.project.name !== 'chromium', 'Run the redirect contract once'); + + const redirects = new Map([ + ['/docs/overview', '/docs/getting-started'], + [ + '/vi/docs/admins/identity-permissions', + '/vi/docs/guides/administration/identity-permissions', + ], + [ + '/docs/deployment/self-hosting.md', + '/docs/guides/deployment-operations/self-hosting.md', + ], + [ + '/docs/developers/api-reference/search-catalog.md', + '/docs/reference/api-reference/search-catalog.md', + ], + ]); + + for (const [source, destination] of redirects) { + const response = await request.get(source, { maxRedirects: 0 }); + expect(response.status(), source).toBe(308); + expect(response.headers().location, source).toBe(destination); + } +}); + test('quickstart exposes executable commands and observable health', async ({ page }) => { - await page.goto('/docs/overview/quickstart'); + await page.goto('/docs/getting-started/quickstart'); await expect( page.getByRole('heading', { level: 1, name: 'Quickstart and POC demo' }), ).toBeVisible(); @@ -154,8 +179,8 @@ test('root and docs pages pass automated accessibility smoke checks', async ({ p for (const route of [ '/', - '/docs/overview', - '/vi/docs/overview', + '/docs/getting-started', + '/vi/docs/getting-started', '/docs/architecture-security/system-description', ]) { await page.goto(route); @@ -176,7 +201,7 @@ test('root and docs pages pass automated accessibility smoke checks', async ({ p }); test('responses carry security headers and use explicit Markdown URLs', async ({ request }) => { - for (const route of ['/docs/overview', '/vi/docs/overview']) { + for (const route of ['/docs/getting-started', '/vi/docs/getting-started']) { const response = await request.get(route, { headers: { Accept: 'text/html', @@ -203,7 +228,7 @@ test('responses carry security headers and use explicit Markdown URLs', async ({ }); test('generated API reference renders with its playground disabled', async ({ page }) => { - await page.goto('/docs/developers/api-reference/search-catalog'); + await page.goto('/docs/reference/api-reference/search-catalog'); await expect( page.getByRole('heading', { level: 1, name: 'Search and catalog' }), diff --git a/docs/increments/active/2026-07-29-public-docs-coauthoring/design.md b/docs/increments/active/2026-07-29-public-docs-coauthoring/design.md new file mode 100644 index 00000000..74bdabf2 --- /dev/null +++ b/docs/increments/active/2026-07-29-public-docs-coauthoring/design.md @@ -0,0 +1,168 @@ +# Public Documentation Co-Authoring Design + +## Problem + +The first public corpus proved the Fumadocs application, publication boundary, +search, API generation, bilingual shell, and independent production delivery. +Its information architecture was intentionally modeled on the much larger Onyx +documentation set. At OrgMemory's current scale, that model creates sparse root +categories and mixes different reader needs: + +- Start Here combines orientation, a tutorial, concepts, and a domain lifecycle; +- Build & Integrate combines task guidance with generated reference; +- System Design combines architecture explanations with thesis evaluation and + requirement traceability; +- Deployment and administration are promoted to roots with only one or two + authored pages. + +The project owner also needs a deliberate learning loop: authoring each page +must improve their own architectural understanding instead of producing a +large corpus for passive review. + +## Goals + +- Establish one durable target information architecture for the public product + documentation. +- Review and publish one document at a time in English and Vietnamese. +- Make the project owner the content owner and architectural learner for every + authored page. +- Keep public product documentation separate from private SRS, SDD, ADR, + increment, test, runbook, and thesis evidence. +- Preserve stable external URLs with redirects when taxonomy changes move a + page. +- Keep every published claim traceable to current repository and runtime + evidence. +- Keep the owner review loop local-first: ordinary page review starts only the + independent docs application and uses hot reload. + +## Non-Goals + +- Bulk rewriting or machine-translating the existing corpus. +- Publishing raw internal repository documentation. +- Turning the public site into an SRS/SDD or university report. +- Creating empty placeholder pages to make a category appear mature. +- Maintaining two competing current-state explanations. + +## Audience And Ownership + +The project owner is the first reader and final editorial owner. Secondary +readers are product users, administrators, self-hosted operators, integrators, +security reviewers, and evaluators. Each public page identifies one primary +reader need and one dominant documentation form. + +The repository remains the engineering source of truth. Public MDX is a +reviewed, audience-oriented projection. Northstar records continuity and next +steps but does not replace repository or runtime evidence. + +## Information-Architecture Decision + +Use four root categories adapted from the Diátaxis reader needs: + +1. **Getting Started** — orientation and the first successful tutorial. +2. **Guides** — task-oriented product, administration, deployment, operations, + and integration procedures. +3. **Architecture & Security** — explanations of system structure, domain + models, data flows, trust boundaries, and design rationale. +4. **Reference** — exact API, configuration, connector, permission, MCP, error, + and compatibility contracts. + +Deployment & Operations remains a Guides subgroup until it has enough reviewed +material to justify an independent root. Changelog remains a global navigation +link rather than a root documentation mode. + +### Strongest Counterargument + +Audience roots such as Deployment, Admins, Developers, and Security provide +direct entry points and match mature enterprise documentation such as Onyx. +Keeping the first-release structure also avoids URL movement. + +### Repository Evidence And Final Choice + +The current manifest has 17 authored pages and seven generated API pages. +Deployment has one authored page; administration has two; the developer root +contains one guide plus generated reference. The sparse roots do not yet earn +separate navigation modes. Fumadocs supports root folders as a presentation +mechanism, so the product should choose roots from reader needs rather than +copying another product's scale. + +Choose the four-root structure now. Preserve old URLs with permanent redirects. +Promote a subgroup only after real reviewed pages and reader demand justify it. + +The rejected alternative is retaining the five current roots and documenting +their overlap. That would describe the inconsistency rather than remove it. + +## Public And Private Documentation Boundary + +Public product documentation lives only under `apps/docs/content/docs`. + +Private engineering and thesis evidence remains in its canonical repository +homes: + +- `docs/specs/domains` — living requirements and domain contracts; +- `docs/decisions` — architectural decisions and rationale; +- `docs/increments` — point-in-time designs and execution history; +- `docs/tests/domains` — mirrored verification coverage and gaps; +- `docs/runbooks` — internal operational procedures; +- university deliverables — thin views over those canonical sources, not a + second product documentation tree. + +Functional coverage, requirement traceability, and academic future-work pages +must not remain mixed into Architecture & Security. A later content increment +will either retire them from public navigation or rewrite a public-safe subset +as capability status or known limitations. + +## Co-Authoring Loop + +One content increment owns one conceptual page and its adjacent reviewed +Vietnamese translation: + +1. **Evidence packet** — inspect current code, schema, contracts, specs, tests, + decisions, and runtime evidence. +2. **Owner context** — ask focused questions until the owner can state the + purpose, boundary, invariants, and important tradeoffs in their own words. +3. **Outline** — agree on the reader question and section structure before + drafting prose. +4. **English draft** — write the canonical public explanation with + `sourceRefs`. +5. **Teach-back checkpoint** — the owner reviews and explains the page back; + unresolved confusion returns to evidence or outline. +6. **Reader test** — test realistic reader questions, ambiguity, assumed + context, links, accessibility, and publication safety. +7. **Vietnamese draft** — translate the approved meaning, not merely the + English sentence structure. +8. **Local review** — inspect both locales through the independent local docs + app without starting product services. +9. **Delivery loop** — run docs gates, PR review, merge, immutable build, + deploy, and live verification. +10. **Continuity** — update the page register and consolidated Northstar + checkpoint. + +Structural increments may change taxonomy or redirects across pages, but they +must not silently rewrite page content. The delivery loop may run +autonomously; content work pauses at the owner context, outline, and teach-back +checkpoints. + +## Definition Of Done For One Page + +- one primary audience and reader question are explicit; +- the owner can explain the page's model and boundaries without reading it; +- every current-behavior claim has current source evidence; +- planned behavior is labeled or excluded; +- English is approved before Vietnamese is authored; +- diagrams exist only when they materially clarify a relationship or flow and + include adjacent explanation and useful alternative text; +- no internal path, private host, secret, customer data, raw runbook, or + unapproved implementation detail is published; +- navigation, links, search, Markdown output, accessibility, and mobile layout + pass; +- the exact merged revision is deployed and verified before the page register + advances. + +## Delivery Sequence + +1. Record this program and close the completed portal-delivery increment. +2. Migrate only the taxonomy, page locations, metadata, manifest, colors, and + redirects; do not rewrite prose. +3. Co-author pages in the queue maintained by `apps/docs/AUTHORING.md`. +4. Re-evaluate category promotion only after reviewed content and reader + evidence change the scale. diff --git a/docs/increments/active/2026-07-29-public-docs-coauthoring/plan.md b/docs/increments/active/2026-07-29-public-docs-coauthoring/plan.md new file mode 100644 index 00000000..b597cf8d --- /dev/null +++ b/docs/increments/active/2026-07-29-public-docs-coauthoring/plan.md @@ -0,0 +1,60 @@ +# Public Documentation Co-Authoring Plan + +Execute the accepted [co-authoring design](design.md) through small, +reviewable increments. One content PR owns one conceptual page and its reviewed +English/Vietnamese pair. Taxonomy-only work is a separate structural PR. + +## Program Foundation + +- [x] Record the target information architecture and strongest counterargument. +- [x] Record the page-by-page co-authoring and teach-back workflow. +- [x] Create the durable page register in `apps/docs/AUTHORING.md`. +- [x] Transfer unfinished content follow-ups from the completed portal + increment. +- [ ] Merge the program foundation and taxonomy migration. + +## Taxonomy Migration + +- [x] Replace the five first-release roots with Getting Started, Guides, + Architecture & Security, and Reference. +- [x] Group product, administration, deployment/operations, and integration + procedures under Guides. +- [x] Move generated and authored API contracts under Reference. +- [x] Preserve every moved public URL with an explicit permanent redirect. +- [x] Keep evaluation/traceability content unchanged until its dedicated + retirement or rewrite increment. +- [x] Update EN/VI metadata, category identity mapping, manifest areas, sitemap, + tests, and internal architecture guidance. +- [x] Verify old and new URLs, desktop/mobile navigation, category colors, + accessibility, search, Markdown siblings, and public-output safety. + +## Page-By-Page Content + +For each queue item in `apps/docs/AUTHORING.md`: + +- [ ] assemble the evidence packet; +- [ ] complete owner context questions; +- [ ] approve the outline; +- [ ] review the English draft; +- [ ] complete the teach-back checkpoint; +- [ ] pass reader testing; +- [ ] approve the Vietnamese draft; +- [ ] pass local and CI gates; +- [ ] merge, deploy, live-verify, and advance only that queue item. + +Repeat this checklist in the page's PR description rather than duplicating a +new increment directory for trivial prose edits. Create a dedicated design only +when the page introduces a material publication, architecture, or security +decision. + +## Exit Gate + +The program remains active while priority pages remain in the queue. It may +close when: + +- the four-root information architecture is stable; +- every priority page is reviewed in both English and Vietnamese; +- the project owner can explain the end-to-end architecture and its principal + trust boundaries from the published corpus; +- remaining pages are ordinary maintenance rather than a structured learning + program. diff --git a/docs/increments/active/2026-07-29-public-docs-coauthoring/verification.md b/docs/increments/active/2026-07-29-public-docs-coauthoring/verification.md new file mode 100644 index 00000000..35da16ef --- /dev/null +++ b/docs/increments/active/2026-07-29-public-docs-coauthoring/verification.md @@ -0,0 +1,26 @@ +# Public Documentation Co-Authoring Verification + +## Taxonomy Migration + +- Frozen workspace install completed without changing the lockfile. +- Sanitized OpenAPI generation produced 110 paths in seven endpoint groups + under `Reference`. +- `pnpm --filter @orgmemory/docs check` passed for API generation, lint, + types, content, manifest, publication policy, route boundaries, and links. +- Production build generated 153 static pages. +- Playwright passed 23 tests across desktop and mobile Chromium, with three + deliberate single-project skips. Coverage includes the four-category + switcher and visual identities, English/Vietnamese shells, permanent legacy + redirects, accessibility, search, Markdown siblings, security headers, + sitemap completeness, and public-output safety. +- The root `corepack pnpm docs:dev` command started the independent docs + application at `http://localhost:3000`; `/healthz` returned HTTP 200 with + body `ok`. No product service or Compose dependency was started. + +Local verification ran on Node 23.11.1 and therefore emitted the expected +engine warning. The repository requires Node 24 or newer; GitHub Actions on the +required version remains the merge authority. + +## Delivery + +Pending PR review, merge, immutable build, deployment, and live verification. diff --git a/docs/increments/active/2026-07-28-public-docs-portal/design.md b/docs/increments/completed/2026-07-28-public-docs-portal/design.md similarity index 100% rename from docs/increments/active/2026-07-28-public-docs-portal/design.md rename to docs/increments/completed/2026-07-28-public-docs-portal/design.md diff --git a/docs/increments/active/2026-07-28-public-docs-portal/plan.md b/docs/increments/completed/2026-07-28-public-docs-portal/plan.md similarity index 96% rename from docs/increments/active/2026-07-28-public-docs-portal/plan.md rename to docs/increments/completed/2026-07-28-public-docs-portal/plan.md index 77e47757..6c2fd6ea 100644 --- a/docs/increments/active/2026-07-28-public-docs-portal/plan.md +++ b/docs/increments/completed/2026-07-28-public-docs-portal/plan.md @@ -184,22 +184,22 @@ publication boundary. seconds; use 5-second connection and 15-second request timeouts. - [x] Configure DNS for `docs.kl3in.tech`; Cloudflare and Google public resolvers return the ZM ingress address. -- [ ] Issue and verify TLS for `docs.kl3in.tech`. -- [ ] Configure Nginx Proxy Manager to forward +- [x] Issue and verify TLS for `docs.kl3in.tech`. +- [x] Configure Nginx Proxy Manager to forward `docs.kl3in.tech -> orgmemory-docs:3000`, with TLS, compression, immutable asset caching, revalidatable document outputs, HSTS after TLS verification, `nosniff`, strict referrer policy, restrictive permissions policy, and framing denial. -- [ ] Verify home, one deep link, search, API reference, `llms.txt`, mobile +- [x] Verify home, one deep link, search, API reference, `llms.txt`, mobile navigation, and container health. -- [ ] Crawl every public route and compare it with the committed allowlist; scan +- [x] Crawl every public route and compare it with the committed allowlist; scan all reachable outputs for internal paths, secrets, and private hosts. - [x] Force one failed canary deployment and prove `deploy-docs.sh` restores the previous image, reruns health/smoke checks, and does not recreate product services. - [x] Retain at least the two most recent verified docs images and record the previous reference before every deployment. -- [ ] Record the deployed revision and public verification evidence. +- [x] Record the deployed revision and public verification evidence. Exit gate: @@ -211,7 +211,9 @@ Exit gate: ## Content Follow-Ups -After the first release has real readers: +After the first release has real readers, these follow-ups move to the +page-by-page public documentation co-authoring program. They are not unfinished +portal-delivery gates: - [ ] Add focused admin and operator procedures driven by support questions. - [ ] Expand the first-release evaluation pages with measured retrieval, diff --git a/docs/increments/active/2026-07-28-public-docs-portal/verification.md b/docs/increments/completed/2026-07-28-public-docs-portal/verification.md similarity index 90% rename from docs/increments/active/2026-07-28-public-docs-portal/verification.md rename to docs/increments/completed/2026-07-28-public-docs-portal/verification.md index 8d11cba7..0efc2d81 100644 --- a/docs/increments/active/2026-07-28-public-docs-portal/verification.md +++ b/docs/increments/completed/2026-07-28-public-docs-portal/verification.md @@ -328,3 +328,36 @@ to be a `200` document. The corrected smoke verifies the final `/docs/overview` URL after following the public redirect, uses Overview for the internal document check, and has a focused regression case alongside the forced-canary rollback proof. + +## Bilingual Reader And Stable Representations + +- [PR #129](https://github.com/kl3inIT/OrgMemory/pull/129) introduced the + controlled English/Vietnamese shell. English retains `/docs/...`; Vietnamese + uses `/vi/docs/...` and visibly falls back to reviewed English until an + adjacent `.vi.mdx` page is approved. +- [PR #131](https://github.com/kl3inIT/OrgMemory/pull/131) made document + representations path-based: document URLs always return HTML and explicit + `.md` siblings return Markdown. +- Immutable image build run `30451325467` and deploy run `30451590994` + published exact commit `0b66134c480e4ef8bb662b23c6b0d8f718be9f4f`. + +## Final Portal Verification + +- [PR #133](https://github.com/kl3inIT/OrgMemory/pull/133) added stable + light/dark visual identities for the five first-release roots while + preserving a neutral technical reader. +- PR CI run `30460090220` and merge CI run `30460338860` passed under Node 24. +- Immutable build and scan run `30460578423` published exact merge commit + `fb1c176b9503a0692a0781b0fa924ac7334e58d3`. +- Deploy run `30460784833` pulled the exact SHA-tagged image, recreated only the + docs service, reached healthy state, and passed all 24 allowlisted routes plus + five public outputs. +- Independent live verification confirmed the root redirect, `/healthz`, all + five route identities, English/Vietnamese parity, application security + headers, and immutable `/_next/static/` caching at + `https://docs.kl3in.tech`. + +The independent portal, publication boundary, bilingual shell, immutable +release path, TLS proxy, rollback contract, and live verification are complete. +Future information-architecture and page-quality work belongs to the +page-by-page public documentation co-authoring program. diff --git a/docs/roadmap.md b/docs/roadmap.md index c0d490dc..de584b88 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -23,6 +23,7 @@ Statuses are `shipped`, `active`, `next`, or `later`. | Identity tenant hardening | shipped | [completed plan](increments/completed/2026-07-27-identity-tenant-hardening/plan.md) | | Multi-provider model control plane | shipped | [completed verification](increments/completed/2026-07-29-multi-provider-model-control-plane/verification.md) | | AI model gateway provider boundary | shipped | [completed verification](increments/completed/2026-07-29-ai-model-gateway-boundary/verification.md) | +| Independent bilingual public documentation portal | shipped | [completed verification](increments/completed/2026-07-28-public-docs-portal/verification.md) | The table is a delivery index, not a second description of current behavior. @@ -38,7 +39,7 @@ The table is a delivery index, not a second description of current behavior. | [LightRAG multi-space query latency](increments/active/2026-07-28-lightrag-query-latency/plan.md) | active | deploy merged repair and capture production before/after timings | | [MCP search reliability](increments/active/2026-07-28-mcp-search-reliability/plan.md) | active | deploy merged timeout repair and prove the production MCP call | | [SCIM provisioning foundation](increments/active/2026-07-27-scim-provisioning-foundation/plan.md) | active | previous-binary/restore rehearsals and two-organization negative evidence | -| [Public documentation portal](increments/active/2026-07-28-public-docs-portal/plan.md) | active | deploy the prepared immutable docs release after owner-provided DNS/TLS and capture live publication/rollback proof | +| [Public docs co-authoring and information architecture](increments/active/2026-07-29-public-docs-coauthoring/plan.md) | active | migrate the four-root taxonomy, then co-author What is OrgMemory? with the owner | The other SCIM directories under `increments/active/` are dependency-ordered future designs inside the active native identity program. They do not become @@ -46,8 +47,8 @@ implementation-active until their predecessor exit gates pass. ## Next — Execution Order -1. Complete owner-controlled DNS/TLS and the live publication/rollback proof - for the deployment-ready Fumadocs portal. +1. Complete the public docs taxonomy migration, then begin the owner-led + page-by-page authoring queue with What is OrgMemory?. 2. Complete the guarded ZM database cutover, runtime health, browser login, upload, GraphRAG, Assistant/citation, restore, rollback, and resource gates. 3. Complete the reproducible demo's real ingestion and permission-evaluation diff --git a/package.json b/package.json index 499009a2..6a8e37b4 100644 --- a/package.json +++ b/package.json @@ -11,7 +11,8 @@ "test": "pnpm --recursive --if-present test", "check:cli": "pnpm --filter @orgmemory/cli typecheck && pnpm --filter @orgmemory/cli test && pnpm --filter @orgmemory/cli build", "check:web": "pnpm --filter @orgmemory/web check:api && pnpm --filter @orgmemory/web typecheck && pnpm --filter @orgmemory/web test:unit && pnpm --filter @orgmemory/web build", - "check:docs": "pnpm --filter @orgmemory/docs check" + "check:docs": "pnpm --filter @orgmemory/docs check", + "docs:dev": "pnpm --filter @orgmemory/docs dev" }, "packageManager": "pnpm@11.9.0+sha512.bd682d5d03fe525ef7c9fd6780c6884d1e756ac4c9c9fe00c538782824310dcf90e3ddc4f53835f06dfaebd5085e41855e0bcbb3b60de2ac5bbab89e5036f03b" } From 797cb41b1374eb2da752abfdf898dd6739b2cfaa Mon Sep 17 00:00:00 2001 From: kl3inIT Date: Wed, 29 Jul 2026 22:04:25 +0700 Subject: [PATCH 2/2] docs: clarify local preview workflow --- apps/docs/AUTHORING.md | 1 + apps/docs/README.md | 11 +++++++++++ 2 files changed, 12 insertions(+) diff --git a/apps/docs/AUTHORING.md b/apps/docs/AUTHORING.md index 3688c163..72aeedd5 100644 --- a/apps/docs/AUTHORING.md +++ b/apps/docs/AUTHORING.md @@ -40,6 +40,7 @@ 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 ``` diff --git a/apps/docs/README.md b/apps/docs/README.md index 256d297a..91668b6a 100644 --- a/apps/docs/README.md +++ b/apps/docs/README.md @@ -8,7 +8,17 @@ Run commands from the repository root: ```powershell corepack pnpm install --frozen-lockfile +``` + +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 ``` @@ -27,5 +37,6 @@ 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 ```