chanora/dev-docs/superpowers/specs/2026-06-13-documentation-site-design.md

# Documentation Site & ASPICE Traceability System Design

**Date:** 2026-06-13
**Status:** Approved design for implementation
**Scope:** Docusaurus doc site, git submodule separation, tag-based ASPICE traceability with custom validation plugin, Cloudflare Pages hosting with access control

## 1. Purpose

Replace the current flat markdown documentation tree with a browseable, searchable, access-controlled doc site that serves three audiences: developers, ASPICE assessors, and non-technical stakeholders. Introduce automated traceability enforcement that validates the ASPICE requirement chain on every build.

## 2. Current State

- 65+ markdown files in `docs/` with no sidebar, no search, no visual hierarchy
- ASPICE traceability maintained in manual markdown tables (`traceability-matrix.md`)
- Cross-references are backtick-quoted paths in prose, not clickable links
- Link coverage report found 2 broken links + 5 broken path references
- No CI enforcement of traceability integrity
- No access control — docs only viewable via GitHub repo browsing or local clone

## 3. Design Decisions

| Decision | Choice | Rationale |
|---|---|---|
| Repo structure | Git submodule (`docs/` → `chanora-docs` repo) | Cleaner separation, access control, CI independence, separate versioning |
| Doc site generator | Docusaurus | Meta-maintained, full plugin API, built-in tags and versioning, active ecosystem |
| Traceability mechanism | Tag-based + custom Docusaurus plugin | Tags for browsing, plugin for automated chain validation and coverage reports |
| Hosting | Cloudflare Pages | Free tier, global CDN, auto-deploy from CI |
| Access control | Cloudflare Access | Free for up to 50 users, email-based auth, SSO support |
| Code path references in docs | Remove from ASPICE docs, move to `impl-mapping.md` | ASPICE traces requirement IDs, not file paths. Code paths are developer convenience |
| Provenance records | Deferred | Completed ASPICE-related plans archived in `dev-docs/superpowers/plans/_archived/` for now |

## 4. Repo Structure

### 4.1 Docs submodule (`chanora-docs` repo)

```
chanora-docs/
├── docusaurus.config.ts
├── sidebars.ts
├── package.json
├── package-lock.json
├── tsconfig.json
├── docs/
│   ├── index.md
│   ├── requirements/
│   │   ├── sysrs.md
│   │   ├── sysdes.md
│   │   └── srs.md
│   ├── architecture/
│   │   ├── sad.md
│   │   ├── sdd.md
│   │   ├── file-transfer-design.md
│   │   ├── file-transfer-research.md
│   │   ├── file-transfer-implementation-plan.md
│   │   └── desktop-ptt-architecture.md
│   ├── verification/
│   │   ├── verification-master-plan.md
│   │   ├── swe4-unit-verification-plan.md
│   │   ├── swe5-software-integration-verification-plan.md
│   │   ├── swe6-software-verification-plan.md
│   │   └── sys4-system-integration-verification-plan.md
│   ├── governance/
│   │   ├── document-index.md
│   │   ├── traceability-matrix.md
│   │   ├── product-decision-register.md
│   │   ├── baseline-approval-record.md
│   │   ├── baseline-candidate-validation-report.md
│   │   ├── document-review-report.md
│   │   ├── document-naming-convention.md
│   │   ├── decision-impact-assessment.md
│   │   ├── git-commit-message-convention.md
│   │   ├── repo-format-validation-report.md
│   │   ├── path-migration-map.md
│   │   └── maintainability-review-2026-06-08.md
│   ├── security/
│   │   ├── security-privacy-legal-guideline.md
│   │   ├── threat-model.md
│   │   ├── secure-storage-audit-report.md
│   │   ├── diagnostic-redaction-audit-report.md
│   │   ├── dependency-and-supply-chain-report.md
│   │   ├── license-inventory.md
│   │   └── flutter-license-inventory.md
│   ├── privacy/
│   │   └── privacy-policy.md
│   ├── legal/
│   │   └── trademark-and-attribution-review.md
│   ├── release/
│   │   ├── platform-release-policy.md
│   │   ├── release-readiness-go-nogo-record.md
│   │   └── dv-waiver-register.md
│   ├── references/
│   │   ├── aspice-swe2-swe3-integration-note.md
│   │   ├── external-references.md
│   │   ├── yatqa-en.md
│   │   ├── yatqa-de.md
│   │   ├── teaspeak-overview.md
│   │   └── respeak-overview.md
│   ├── ui-ux/
│   │   ├── material3-guideline.md
│   │   ├── material3-design-tokens.md
│   │   ├── material3-component-catalog.md
│   │   └── adaptive-layout-platform-guide.md
│   └── i18n/
│       └── localization-architecture.md
├── plugins/
│   └── traceability/
│       └── index.js
├── scripts/
│   ├── validate-traceability.mjs
│   └── add-requirement-tags.mjs
├── src/
│   ├── pages/index.tsx
│   └── css/custom.css
├── static/
│   └── img/
├── .github/
│   └── workflows/
│       └── deploy.yml
├── wrangler.toml
└── README.md
```

### 4.2 Code repo local files

```
chanora/
├── docs/ → chanora-docs (submodule)
├── dev-docs/
│   ├── superpowers/
│   │   ├── specs/
│   │   │   ├── 2026-05-28-server-resolution-prefetch-design.md
│   │   │   ├── 2026-05-28-chanora-server-prefetch-crate-design.md
│   │   │   ├── 2026-05-29-state-sync-ui-settings-validation-design.md
│   │   │   ├── 2026-06-05-adaptive-3-panel-layout-design.md
│   │   │   ├── 2026-06-08-maintainability-continuation-design.md
│   │   │   ├── 2026-06-09-poke-without-message-design.md
│   │   │   └── 2026-06-13-documentation-site-design.md
│   │   └── plans/
│   │       ├── _archived/
│   │       │   ├── 2026-05-29-finish-dv-document-tree.md
│   │       │   ├── 2026-05-29-dv-evidence-pack.md
│   │       │   ├── 2026-05-29-swe2-swe3-baselines.md
│   │       │   └── 2026-05-29-state-sync-ui-settings-validation.md
│   │       ├── 2026-05-28-server-resolution-prefetch.md
│   │       ├── 2026-05-28-chanora-server-prefetch-crate.md
│   │       ├── 2026-06-06-chat-panel-switching.md
│   │       ├── 2026-06-08-core-internal-split.md
│   │       └── 2026-06-08-maintainability-continuation.md
│   ├── offline-knowledge/
│   │   ├── coverage-analysis.md
│   │   ├── doc-quality-analysis.md
│   │   ├── link-coverage-report.md
│   │   └── reviews/
│   ├── implementation-status-2026-05-28.md
│   ├── release/ios-build.md
│   └── impl-mapping.md
├── apps/, crates/, core/
├── AGENTS.md
└── README.md
```

## 5. Docusaurus Configuration

### 5.1 Site configuration (`docusaurus.config.js`)

```js
module.exports = {
  title: 'Chanora Engineering Docs',
  tagline: 'ASPICE-compliant engineering documentation with automated traceability',
  url: 'https://docs.chanora.dev',
  baseUrl: '/',
  organizationName: 'chanoraapp',
  projectName: 'docs',
  onBrokenLinks: 'throw',
  onBrokenMarkdownLinks: 'warn',
  i18n: { defaultLocale: 'en', locales: ['en'] },
  themes: ['@docusaurus/theme-classic'],
  plugins: [
    './plugins/traceability',
  ],
  themeConfig: {
    navbar: {
      title: 'Chanora Docs',
      items: [
        { type: 'doc', position: 'left', label: 'Requirements', docId: 'requirements/sysrs' },
        { type: 'doc', position: 'left', label: 'Architecture', docId: 'architecture/sad' },
        { type: 'doc', position: 'left', label: 'Verification', docId: 'verification/verification-master-plan' },
        { type: 'doc', position: 'left', label: 'Governance', docId: 'governance/document-index' },
        { type: 'doc', position: 'left', label: 'Security', docId: 'security/security-privacy-legal-guideline' },
        { type: 'doc', position: 'left', label: 'Release', docId: 'release/platform-release-policy' },
        { type: 'doc', position: 'left', label: 'References', docId: 'references/external-references' },
        { type: 'doc', position: 'left', label: 'UI/UX', docId: 'ui-ux/material3-guideline' },
        { type: 'tags' },
      ],
    },
    footer: {
      style: 'dark',
      links: [
        { title: 'Docs', items: [
          { label: 'Requirements', to: '/docs/requirements/sysrs' },
          { label: 'Architecture', to: '/docs/architecture/sad' },
          { label: 'Verification', to: '/docs/verification/verification-master-plan' },
        ]},
        { title: 'Governance', items: [
          { label: 'Traceability Matrix', to: '/docs/governance/traceability-matrix' },
          { label: 'Decision Register', to: '/docs/governance/product-decision-register' },
          { label: 'Document Index', to: '/docs/governance/document-index' },
        ]},
      ],
    },
    prism: { theme: prismThemes.github, darkTheme: prismThemes.dracula },
  },
};
```

### 5.2 Sidebar (`sidebars.js`)

```js
module.exports = {
  requirements: [
    'requirements/sysrs',
    'requirements/sysdes',
    'requirements/srs',
  ],
  architecture: [
    'architecture/sad',
    'architecture/sdd',
    'architecture/file-transfer-design',
    'architecture/file-transfer-research',
    'architecture/file-transfer-implementation-plan',
    'architecture/desktop-ptt-architecture',
  ],
  verification: [
    {
      type: 'category',
      label: 'System Level',
      items: ['verification/sys4-system-integration-verification-plan'],
    },
    {
      type: 'category',
      label: 'Software Integration',
      items: ['verification/swe5-software-integration-verification-plan'],
    },
    {
      type: 'category',
      label: 'Unit Level',
      items: ['verification/swe4-unit-verification-plan'],
    },
    {
      type: 'category',
      label: 'Software Qualification',
      items: ['verification/swe6-software-verification-plan'],
    },
    'verification/verification-master-plan',
  ],
  governance: [
    'governance/document-index',
    'governance/traceability-matrix',
    'governance/product-decision-register',
    'governance/baseline-approval-record',
    'governance/baseline-candidate-validation-report',
    'governance/document-review-report',
    'governance/document-naming-convention',
    'governance/decision-impact-assessment',
    'governance/git-commit-message-convention',
    'governance/repo-format-validation-report',
    'governance/path-migration-map',
    'governance/maintainability-review-2026-06-08',
  ],
  security: [
    'security/security-privacy-legal-guideline',
    'security/threat-model',
    'security/secure-storage-audit-report',
    'security/diagnostic-redaction-audit-report',
    'security/dependency-and-supply-chain-report',
    'security/license-inventory',
    'security/flutter-license-inventory',
    'privacy/privacy-policy',
    'legal/trademark-and-attribution-review',
  ],
  release: [
    'release/platform-release-policy',
    'release/release-readiness-go-nogo-record',
    'release/dv-waiver-register',
  ],
  references: [
    'references/external-references',
    'references/aspice-swe2-swe3-integration-note',
    'references/yatqa-en',
    'references/yatqa-de',
    'references/teaspeak-overview',
    'references/respeak-overview',
  ],
  uiux: [
    'ui-ux/material3-guideline',
    'ui-ux/material3-design-tokens',
    'ui-ux/material3-component-catalog',
    'ui-ux/adaptive-layout-platform-guide',
    'i18n/localization-architecture',
  ],
};
```

## 6. Tag-Based Traceability

### 6.1 Front matter schema

Every document includes YAML front matter:

```yaml
---
tags: [swe.2, architecture, SRS-003, SRS-008, SRS-016]
upstream: [srs, sysdes]      # Custom metadata for traceability plugin
downstream: [sdd, swe4, swe5] # Custom metadata for traceability plugin
lifecycle: SWE.2              # Custom metadata for traceability plugin
status: baseline              # Custom metadata for traceability plugin
---
```

The `tags` field is consumed by the Docusaurus tags system for browsing. The `upstream`, `downstream`, `lifecycle`, and `status` fields are custom metadata consumed by the traceability plugin for chain validation.

### 6.2 Tag categories

| Tag pattern | Purpose | Example |
|---|---|---|
| `swe.1` through `swe.6`, `sys.4` | ASPICE lifecycle stage | Every doc gets at least one |
| `sysrs`, `sysdes`, `srs`, `sad`, `sdd` | Document type | Identifies the doc in the chain |
| `requirements`, `architecture`, `verification`, `governance` | Section category | For filtering |
| `SysRS-233`, `SRS-045`, `SDD-MOD-009` | Requirement/module IDs | Traceability links |
| `baseline`, `draft`, `candidate` | Document status | Assessor visibility |
| `dec-012`, `dec-020` | Decision register refs | Cross-ref to governance |

### 6.3 Section defaults

Docusaurus uses front matter `tags:` per document. Section-level defaults are not needed since each document carries its own tags.

### 6.4 Verification page trace mappings

| Verification plan | Upstream traces | Tags |
|---|---|---|
| SYS.4 System Integration | SysDes, SysRS | `[sys.4, verification, SysDes-102, SysDes-103, ...]` |
| SWE.5 Software Integration | SAD (SWE.2) | `[swe.5, verification, sad-component-bridge, ...]` |
| SWE.4 Unit Verification | SDD (SWE.3) | `[swe.4, verification, SDD-MOD-001, ...]` |
| SWE.6 Software Verification | SRS | `[swe.6, verification, SRS-128, ...]` |

## 7. Custom Traceability Plugin

### 7.1 Location

`plugins/traceability/index.js` — Docusaurus plugin, ~100 lines JavaScript.

### 7.2 Behavior

On `on_page_markdown` event:
- Scan each page for requirement ID patterns: `SysRS-\d+`, `SysDes-\d+`, `SRS-\d+`, `SDD-MOD-\d+`, `DEC-\d+`
- Build an in-memory traceability graph: upstream ID → downstream document → verification plan

On `on_post_build` event:
- Validate every requirement ID referenced downstream exists in its source document
- Validate every upstream document ID has at least one downstream allocation
- Flag orphaned references (IDs mentioned but never defined)
- Verify bidirectional completeness

### 7.3 Outputs

- `traceability-coverage.json` — machine-readable coverage report with chain completeness percentages
- Console output with pass/fail summary
- Traceability dashboard page with coverage table and broken chain details
- Build failure (`sys.exit(1)`) on broken chains when `strict: true`

### 7.4 Standalone CI validator

`scripts/validate-traceability.mjs` — same validation logic, runnable without Docusaurus build:

```
python scripts/validate_traceability.py docs/
```

Exit code 0 = all chains valid. Exit code 1 = broken chains with details on stderr.

## 8. Hosting & Deployment

### 8.1 Architecture

```
chanora-docs repo → push to main → GitHub Actions
    → validate-traceability.mjs
    → npm run build
    → Cloudflare Pages (via Wrangler)
        → Cloudflare Access policy (email-based auth)
```

### 8.2 CI workflow

On pull request: build + validate only (no deploy).
On push to main: build + validate + deploy to Cloudflare Pages.

### 8.3 Cloudflare Access policy

- Free tier for up to 50 users
- Email-based authentication with optional Google/GitHub SSO
- One-time PIN for external assessors
- Access rules: allow company emails, specific assessor emails; block all others

## 9. Migration Plan

### 9.1 Code path reference cleanup

SAD and SDD currently list file paths (`crates/chanora_protocol/src/`) in component tables. These references will be:
- Replaced with component/module IDs only in the docs submodule
- Preserved in `dev-docs/impl-mapping.md` in the code repo for developer convenience

### 9.2 File moves

| From (code repo) | To | Action |
|---|---|---|
| `docs/sysrs.md` | docs submodule | Move + add front matter |
| `docs/sysdes.md` | docs submodule | Move + add front matter |
| `docs/srs.md` | docs submodule | Move + add front matter |
| `docs/requirements/*` | docs submodule | Move (path records) |
| `docs/architecture/*` | docs submodule | Move + cleanup code paths |
| `docs/verification/*` | docs submodule | Move + add front matter |
| `docs/governance/*` | docs submodule | Move + add front matter |
| `docs/security/*` | docs submodule | Move + add front matter |
| `docs/privacy/*` | docs submodule | Move |
| `docs/legal/*` | docs submodule | Move |
| `docs/release/policy+go-nogo+waiver` | docs submodule | Move |
| `docs/references/*` | docs submodule | Move |
| `docs/ui-ux/*` | docs submodule | Move |
| `docs/i18n/*` | docs submodule | Move |
| `docs/material3-guideline.md` | docs submodule | Move |
| `docs/offline-knowledge/external/*` | docs submodule `references/` (flattened) | Move + rename |
| `docs/superpowers/*` | `dev-docs/superpowers/` | Move |
| `docs/offline-knowledge/` (remaining) | `dev-docs/offline-knowledge/` | Move |
| `docs/implementation-status-*` | `dev-docs/` | Move |
| `docs/release/ios-build.md` | `dev-docs/release/` | Move |

### 9.3 Cross-reference updates

All backtick path references (`docs/srs.md`) should become markdown links (`[SRS](../srs.md)` or `[SRS](srs.md)`) for both GitHub and Docusaurus rendering.

### 9.4 Post-migration

- Remove `docs/` contents from code repo
- Add `chanora-docs` as git submodule at `docs/`
- Create `dev-docs/` directory with local-only files
- Update README references to new paths
- Write `AGENTS.md` with new conventions
- Update `opencode.json` or `.opencode/` references

## 10. AGENTS.md

An `AGENTS.md` file will be written at the code repo root documenting:
- The two-repo model (docs/ as submodule, dev-docs/ as local)
- What content goes where
- ASPICE traceability chain and rules
- Code architecture overview
- Verification commands
- Agent working conventions (no edits in docs/ without submodule awareness)

## 11. Deferred Items

| Item | Reason | When |
|---|---|---|
| Document provenance records | Convert completed ASPICE plans into provenance evidence | Follow-up task |
| Custom Docusaurus traceability plugin | Core feature, built during implementation | Phase 1 |
| Cloudflare Pages + Access setup | Requires account creation, domain config | During deployment |
| `impl-mapping.md` creation | Extract code paths from SAD/SDD during migration | During migration |