Split docs into user and developer wikis

.github/workflows/mkdocs.yml

@@ -51,9 +51,10 @@ jobs:
         run: |
           set -e
           test -f Docs/Published/index.md
-          for d in API-related Code_Documentation Deployment Evaluations Monitoring User_Guides; do
+          for d in API-related ADR Code_Documentation Deployment Evaluations Monitoring User_Guides Wiki; do
             test -d "Docs/Published/$d" || { echo "Missing Docs/Published/$d"; exit 1; }
           done
+          test -f Docs/Published/Architecture.md || { echo "Missing Docs/Published/Architecture.md"; exit 1; }
           # Ensure there are Markdown files to build
           count=$(find Docs/Published -type f -name "*.md" | wc -l)
           echo "Markdown files found: $count"

Docs/Code_Documentation/Docs_Site_Guide.md

@@ -12,17 +12,30 @@ This document explains how the tldw_Server documentation site is organized, buil
 
 The public docs site is for OSS, self-host, and developer documentation. Hosted/commercial docs are excluded from the published site and should live in the private repo instead of this public docs pipeline.
 
+The published site is audience-first:
+
+- `User Wiki`: install, run, configure, and use tldw_server.
+- `Developer Wiki`: contribute to, test, package, and understand the codebase.
+
+These wiki pages are MkDocs landing pages in this repository, not the separate GitHub Wiki feature.
+
 ## What Gets Published
 
 Only these folders are included on the public site:
 
+- `Docs/Wiki`
 - `Docs/API-related`
+- `Docs/ADR`
 - `Docs/Code_Documentation`
 - `Docs/Deployment` (excluding its nested `Monitoring`)
 - `Docs/Deployment/Monitoring` (published as top-level `Monitoring`)
 - `Docs/Evals`
 - `Docs/User_Guides`
 
+These root-level files are also included when present:
+
+- `Docs/Architecture.md`
+
 The curated content is synced into `Docs/Published/`. Do not manually edit files in `Docs/Published/` - they can be overwritten by the refresh script or CI.
 
 Hosted/commercial docs are excluded from this curated set even when they live under similarly named source areas. If a page exists mainly to run, sell, support, or differentiate the hosted SaaS service, keep it in the private repo rather than adding it to the public docs tree.
@@ -32,6 +45,9 @@ Hosted/commercial docs are excluded from this curated set even when they live un
 - Script: `Helper_Scripts/refresh_docs_published.sh`
 - What it does:
   - Copies the approved folders from `Docs/` to `Docs/Published/`
+  - Copies the audience wiki landing pages from `Docs/Wiki`
+  - Copies architecture decision records from `Docs/ADR`
+  - Copies `Docs/Architecture.md` when present
   - Promotes `Docs/Deployment/Monitoring` to top-level `Docs/Published/Monitoring`
   - Removes the nested `Monitoring` under `Deployment` to avoid duplication
   - Preserves each section's `index.md` landing page
@@ -88,6 +104,9 @@ To change the logo: replace `Docs/Logo.png` and run the refresh script.
 - The sidebar and ordering are defined explicitly in `mkdocs.yml` under `nav:`
 - When adding a new page you want visible in the sidebar, add a new entry under the appropriate section in `mkdocs.yml`
 - The nav uses paths relative to `Docs/Published/`
+- Keep the top-level navigation audience-first: `Home`, `User Wiki`, `Developer Wiki`, and shared reference links.
+- User-facing workflow docs belong under the `User Wiki` nav tree.
+- Contributor, implementation, architecture, and docs-maintenance material belongs under the `Developer Wiki` nav tree.
 
 Example nav entry (under Code section):
 
@@ -107,6 +126,10 @@ Tip: keep titles short and parallel (e.g., "Guide", "Reference", "Checklist").
 5. Commit and push; CI will refresh, build, and deploy the site
 
 Notes:
+- Put audience chooser pages in `Docs/Wiki/`
+- Put user-facing workflow guides in `Docs/User_Guides/` or `Docs/Getting_Started/`
+- Put contributor-facing implementation guides in `Docs/Code_Documentation/`
+- Put public architecture decision records in `Docs/ADR/`
 - Keep file names stable after they’re published to avoid broken links
 - Use relative links within the allowed folders; avoid linking to WIP docs outside the curated set
 - Prefer images stored under `Docs/assets/` or section subfolders; the refresh script copies section contents

Docs/Published/ADR/000-template.md

@@ -0,0 +1,30 @@
+# ADR-{N}: {Short title}
+
+**Status:** Proposed | Accepted | Superseded by ADR-{N}
+**Date:** YYYY-MM-DD
+**Backfilled from:** {source path, or "not backfilled"}
+**Decision owner:** {human/session/reviewer}
+**Related task:** {Backlog task ID/link}
+**Related spec/plan:** {paths}
+
+## Decision
+
+One sentence stating what was decided.
+
+## Context
+
+Why this decision was needed.
+
+## Alternatives considered
+
+| Option | Why rejected |
+| --- | --- |
+| {Alternative A} | {Reason} |
+
+## Consequences
+
+What this means going forward, including accepted tradeoffs.
+
+## Follow-up
+
+Optional implementation, audit, or documentation follow-up links.

Docs/Published/ADR/001-adr-workflow-and-governance.md

@@ -0,0 +1,32 @@
+# ADR-001: ADR Workflow And Governance
+
+**Status:** Accepted
+**Date:** 2026-06-02
+**Backfilled from:** not backfilled
+**Decision owner:** User + Codex collaboration session
+**Related task:** TASK-506, TASK-507, TASK-508
+**Related spec/plan:** `Docs/superpowers/specs/2026-06-02-adr-workflow-adoption-design.md`, `Docs/superpowers/plans/2026-06-02-adr-workflow-adoption-stage-1-implementation-plan.md`
+
+## Decision
+
+Use `Docs/ADR/` as the canonical home for Architecture Decision Records and require ADR assessment for substantial specs, implementation plans, and PRs.
+
+## Context
+
+Architecture decisions existed in scattered design docs, plans, review packets, and embedded ADR-like sections. The project needs a lightweight durable record that explains why architectural rules exist without replacing Backlog.md, Superpowers specs, implementation plans, or module documentation.
+
+## Alternatives considered
+
+| Option | Why rejected |
+| --- | --- |
+| Big-bang migration | Too much churn and too high a risk of converting stale decisions into accepted policy. |
+| Decision index before ADRs | Safer for audit, but delays the actual ADR workflow. |
+| Module-by-module only | Too passive; it would not establish a repo-wide standard. |
+
+## Consequences
+
+Significant durable architecture decisions need ADRs. Substantial specs, plans, and PRs need an explicit ADR assessment. Accepted ADRs are immutable except for supersession metadata. Backfilled decisions use source metadata rather than pretending they were written at decision time.
+
+## Follow-up
+
+Create follow-up Backlog tasks for the decision inventory, module-by-module backfill, and possible global Superpowers updates.

Docs/Published/ADR/002-backlog-md-task-tracking.md

@@ -0,0 +1,32 @@
+# ADR-002: Backlog.md Task Tracking
+
+**Status:** Accepted
+**Date:** 2026-06-02
+**Backfilled from:** `AGENTS.md`, `Docs/superpowers/specs/2026-05-03-backlog-md-task-tracking-design.md`
+**Decision owner:** User + prior Codex collaboration session
+**Related task:** TASK-506, TASK-507, TASK-508
+**Related spec/plan:** `Docs/superpowers/specs/2026-05-03-backlog-md-task-tracking-design.md`
+
+## Decision
+
+Require an associated Backlog.md task before work changes repository files.
+
+## Context
+
+The repository needs a durable task and history layer that records why work exists, how it was planned, what files changed, what verification ran, and what was skipped or blocked.
+
+## Alternatives considered
+
+| Option | Why rejected |
+| --- | --- |
+| Git commits only | Commits do not capture task state, verification history, blockers, or reviewable unit boundaries. |
+| GitHub issues only | Not every local agent task maps cleanly to a remote issue, and local work needs MCP/CLI-first task tracking. |
+| Manual markdown notes | Too easy to duplicate or bypass; Backlog.md provides a consistent task workflow. |
+
+## Consequences
+
+Repo-changing work must search for or create a Backlog task before edits begin. Read-only investigation can proceed without a task. Backlog tasks link to specs, plans, PRs, verification, and final summaries; they do not replace those artifacts.
+
+## Follow-up
+
+None for Stage 1.

Docs/Published/ADR/003-jobs-vs-scheduler-default.md

@@ -0,0 +1,32 @@
+# ADR-003: Jobs Vs Scheduler Default
+
+**Status:** Accepted
+**Date:** 2026-06-02
+**Backfilled from:** `AGENTS.md`
+**Decision owner:** User + prior project guidance
+**Related task:** TASK-506, TASK-507, TASK-508
+**Related spec/plan:** `Docs/superpowers/specs/2026-06-02-adr-workflow-adoption-design.md`
+
+## Decision
+
+Use Jobs by default for new user-visible work that needs admin or ops visibility, and use Scheduler for internal orchestration where dependency handling is central.
+
+## Context
+
+The project has both Jobs and Scheduler systems. Future contributors need a durable default to avoid ad hoc queue/orchestration choices.
+
+## Alternatives considered
+
+| Option | Why rejected |
+| --- | --- |
+| Jobs for all async work | Internal dependency orchestration fits Scheduler better and does not always need user/admin controls. |
+| Scheduler for all async work | User-facing work often needs pause, resume, drain, retries, quotas, RLS, status endpoints, and worker processes. |
+| Decide per feature with no default | Repeated debates and inconsistent ownership would slow implementation and increase maintenance cost. |
+
+## Consequences
+
+New user-visible features or work needing admin controls should use Jobs. Internal orchestration with task dependencies, idempotency keys, and registered handlers should use Scheduler. Recurring schedules use APScheduler to enqueue into whichever backend the feature chooses.
+
+## Follow-up
+
+Later ADR inventory work should identify any module-specific exceptions.

Docs/Published/ADR/004-ai-generated-pr-change-summary-gate.md

@@ -0,0 +1,32 @@
+# ADR-004: AI-Generated PR Change Summary Gate
+
+**Status:** Accepted
+**Date:** 2026-06-02
+**Backfilled from:** `AGENTS.md`, `Docs/superpowers/AI_GENERATED_PR_CHANGE_SUMMARY_POLICY_2026_04_17.md`
+**Decision owner:** User + prior project guidance
+**Related task:** TASK-506, TASK-507, TASK-508
+**Related spec/plan:** `Docs/superpowers/AI_GENERATED_PR_CHANGE_SUMMARY_POLICY_2026_04_17.md`
+
+## Decision
+
+Materially AI-authored PRs are not merge-ready until the human requester writes a `Change summary` explaining what changed and why those implementation choices were made.
+
+## Context
+
+The project allows AI-assisted development but needs human ownership of architectural and implementation rationale before merge.
+
+## Alternatives considered
+
+| Option | Why rejected |
+| --- | --- |
+| Allow AI-generated summaries | A diff recap or AI-authored rationale does not prove human understanding or ownership. |
+| Require no summary | Reviewers lose a concise human explanation of why the implementation is the right one. |
+| Ban AI-authored PRs | Too restrictive for the project workflow. |
+
+## Consequences
+
+AI-generated PRs need a human-written summary. If the requester cannot explain the rationale in their own words, the PR is not merge-ready. Agents may prepare context, but the merge gate requires human ownership.
+
+## Follow-up
+
+None for Stage 1.

Docs/Published/ADR/005-bandit-touched-scope-security-gate.md

@@ -0,0 +1,32 @@
+# ADR-005: Bandit Touched-Scope Security Gate
+
+**Status:** Superseded by ADR-006
+**Date:** 2026-06-02
+**Backfilled from:** `AGENTS.md`
+**Decision owner:** User + prior project guidance
+**Related task:** TASK-506, TASK-507, TASK-508
+**Related spec/plan:** `Docs/superpowers/specs/2026-06-02-adr-workflow-adoption-design.md`
+
+## Decision
+
+Run Bandit on touched Python/code scope before considering work complete; for docs-only changes, document why Bandit is not applicable.
+
+## Context
+
+The project handles authentication, media ingestion, sandboxing, providers, and local/self-hosted data. Security-sensitive Python changes need an explicit security scan gate that scales to the touched scope.
+
+## Alternatives considered
+
+| Option | Why rejected |
+| --- | --- |
+| Full-repo Bandit every time | Can be expensive and noisy for narrow changes. |
+| No routine Bandit gate | Security regressions in touched code could be missed. |
+| Run only in CI | Local completion should catch new findings before review. |
+
+## Consequences
+
+Agents should activate the project virtual environment and run `python -m bandit -r <touched_paths> -f json -o /tmp/bandit_<task>.json` for touched Python/code paths. New findings in changed code should be fixed before finishing. Docs-only work records Bandit as not applicable.
+
+## Follow-up
+
+None for Stage 1.

Docs/Published/ADR/006-bandit-report-path-portability.md

@@ -0,0 +1,33 @@
+# ADR-006: Bandit Report Path Portability
+
+**Status:** Accepted
+**Date:** 2026-06-03
+**Backfilled from:** not backfilled
+**Decision owner:** User + Codex collaboration session
+**Related task:** TASK-512
+**Related spec/plan:** PR #2230 review follow-up
+**Supersedes:** ADR-005
+
+## Decision
+
+Bandit remains required for touched Python/code scope, but report output paths must be portable and must not hard-code `/tmp`.
+
+## Context
+
+ADR-005 established the touched-scope Bandit gate but used `/tmp/bandit_<task>.json` as the example report path. The project supports Windows, macOS, and Linux, so hard-coding a Unix temporary directory makes the guidance less portable and creates unnecessary friction for agents working outside Unix-like environments.
+
+## Alternatives considered
+
+| Option | Why rejected |
+| --- | --- |
+| Keep `/tmp/bandit_<task>.json` | Not portable to all supported platforms. |
+| Use platform-specific temporary environment variables | Adds shell-specific complexity to a simple project guidance command. |
+| Omit the report output path | Loses the durable JSON artifact useful for recording verification evidence. |
+
+## Consequences
+
+Agents should activate the project virtual environment and run `python -m bandit -r <touched_paths> -f json -o bandit_<task>.json` or another explicitly chosen portable output path for touched Python/code paths. New findings in changed code should be fixed before finishing. Docs-only work records Bandit as not applicable. Generated `bandit_*.json` report artifacts are ignored by `.gitignore` and should not be committed unless explicitly requested.
+
+## Follow-up
+
+None for this follow-up.

Docs/Published/ADR/007-research-workspace-canonical-first-slice-shell.md

@@ -0,0 +1,37 @@
+# ADR-007: Research Workspace Canonical First-Slice Shell
+
+**Status:** Accepted
+**Date:** 2026-06-03
+**Backfilled from:** `Docs/Design/Workspace_Canonical_Model_Decision_2026_05.md`, `Docs/superpowers/specs/2026-05-06-tldw-product-roadmap-design.md`, `Docs/superpowers/plans/2026-05-06-tldw-product-roadmap-first-slice-implementation-plan.md`
+**Decision owner:** Human requester approval of TASK-509 inventory defaults
+**Related task:** TASK-514
+**Related spec/plan:** `Docs/superpowers/plans/2026-06-03-adr-follow-up-sprint-implementation-plan.md`
+
+## Decision
+
+Use `ResearchWorkspace` as the canonical shell for the first roadmap slice while keeping `ChatWorkspace` and `DocumentWorkspace` as specialized routes or modes instead of deleting or fully merging them.
+
+## Context
+
+The workspace roadmap needs one product model for sources, selected sources, chat, quick notes, generated artifacts, saved workspaces, source transfer, local persistence, and server sync boundaries. `ResearchWorkspace` already contains the broadest version of that model and is the best first-slice shell. `ChatWorkspace` and `DocumentWorkspace` still validate important workflows, but they should not define parallel product models during this slice.
+
+The first slice should consolidate the model before consolidating routes. Route consolidation remains a later decision.
+
+## Alternatives considered
+
+| Option | Why rejected |
+| --- | --- |
+| Fully merge `ChatWorkspace` and `DocumentWorkspace` into `ResearchWorkspace` immediately | Too much route and workflow churn for the first slice; it risks breaking existing chat-first and document-focused flows before the shared model is stable. |
+| Keep all three workspaces as independent product models | Creates duplicated state, divergent persistence semantics, and unclear roadmap ownership. |
+| Create a new roadmap workspace from scratch | Duplicates existing `ResearchWorkspace` capabilities and delays first-value work. |
+
+## Consequences
+
+`ResearchWorkspace` owns the first-slice canonical workspace direction. `ChatWorkspace` and `DocumentWorkspace` remain available as specialized entry points or modes. Implementation plans should update the canonical model or write a new ADR before changing route ownership semantics.
+
+Server sync should use the existing `/api/v1/workspaces` family first, while browser-local workspace state remains a responsive cache and offline-friendly UI surface.
+
+## Follow-up
+
+- Use this ADR as the covering record for `INV-017` and the route-consolidation context in `INV-019`.
+- If later work fully merges or removes `ChatWorkspace` or `DocumentWorkspace`, create a superseding ADR.

Docs/Published/ADR/008-workspace-split-key-persistence-and-indexeddb-offload.md

@@ -0,0 +1,37 @@
+# ADR-008: Workspace Split-Key Persistence And IndexedDB Offload
+
+**Status:** Accepted
+**Date:** 2026-06-03
+**Backfilled from:** `Docs/Design/Workspace_Persistence_Architecture.md`
+**Decision owner:** Human requester approval of TASK-509 inventory defaults
+**Related task:** TASK-514
+**Related spec/plan:** `Docs/superpowers/plans/2026-06-03-adr-follow-up-sprint-implementation-plan.md`
+
+## Decision
+
+Persist browser-local workspace state using split `localStorage` keys with optional IndexedDB offload for heavy chat sessions and artifact payloads.
+
+## Context
+
+The Research Workspace persistence path outgrew a single monolithic `localStorage` blob. Workspaces need responsive browser-local state, offline-friendly behavior, migration from legacy payloads, and bounded storage growth while server-backed workspace APIs continue to provide the long-term sync surface.
+
+The split-key model stores an index under `tldw-workspace` and per-workspace snapshot/chat payloads under workspace-specific keys. Heavy chat and artifact payloads can be offloaded to IndexedDB and replaced with pointer metadata.
+
+## Alternatives considered
+
+| Option | Why rejected |
+| --- | --- |
+| Keep one monolithic `localStorage` payload | Increases write churn, payload size risk, and recovery difficulty as workspace count and artifact size grow. |
+| Move all browser workspace persistence to IndexedDB | Adds complexity for every read/write path and removes a simple compatibility path for smaller payloads. |
+| Make server persistence the only source for workspace UI state | Loses responsive local cache behavior and offline-friendly workflows; server sync is not yet the only required client state surface. |
+
+## Consequences
+
+Workspace persistence has a split index plus per-workspace payload keys. IndexedDB offload is feature-gated and optional, and failures fall back to inline payloads when possible. Legacy monolith payloads remain readable and are migrated into the split model.
+
+Persistence code must preserve payload bounds, cleanup stale per-workspace keys/offload records, and keep source-lineage and artifact metadata available even when heavy payload fields are offloaded.
+
+## Follow-up
+
+- Use this ADR as the covering record for `INV-018`.
+- If server-backed workspace sync becomes the only accepted source of persisted workspace truth, create a superseding ADR.