docs: fix documentation to match implementation

- Replace 'Gemini CLI' with 'OpenCode Framework'
- Replace /maintenance with /audit throughout
- Remove references to unimplemented commands (/learn, /document, /brainstorm, /cron)
- Update directory paths to .knowledge/* structure
- Update install.sh to non-interactive mode with --link flag
- Fix install URLs to apiad.github.io/opencode
- Update agent and subagent tables to match actual implementation

Author: apiad

.knowledge/notes/audits/documentation-2026-03-27.md

@@ -0,0 +1,140 @@
+---
+id: audit-documentation-2026-03-27
+created: 2026-03-27
+type: audit
+scope: documentation
+status: active
+---
+
+# Audit: Documentation
+
+## Executive Summary
+
+**Health: ⚠️ Critical Issues**
+
+The documentation has significant drift from the current implementation. Multiple commands referenced don't exist, directory structures are outdated, and install URLs are inconsistent across files. New users following the docs would encounter broken commands and incorrect paths.
+
+## Architecture Overview
+
+### Documentation Files
+- `docs/index.md` — Landing page, philosophy, quick start
+- `docs/deploy.md` — Installation & setup
+- `docs/design.md` — Architecture & systems
+- `docs/develop.md` — Contribution guidelines
+- `docs/updating.md` — Update procedures
+- `docs/user-guide.md` — Usage walkthrough
+- `docs/install.sh` — Installer script
+
+### Actual Command Set (`.opencode/commands/`)
+```
+audit, build, commit, draft, fix, help, investigate, 
+note, onboard, plan, publish, research, scaffold, todo
+```
+
+---
+
+## Findings
+
+### Strengths
+- Clean structure with separate concern files
+- Good use of YAML frontmatter standards
+- README.md accurately reflects two-repo architecture
+- Install script is functional and recent
+
+### Concerns
+
+| Area | Severity | Description | Location | Recommendation |
+|------|----------|-------------|----------|----------------|
+| Directory Structure | **high** | `design.md` shows old dirs (`plans/`, `journal/`, `research/`, `drafts/`) but actual is `.knowledge/plans/`, `.knowledge/log/`, `.knowledge/notes/`, `.knowledge/drafts/` | `docs/design.md:115-127` | Update to show `.knowledge/*` structure |
+| Missing Commands | **high** | `/maintenance`, `/document`, `/brainstorm`, `/cron`, `/learn` are documented but don't exist | Multiple docs | Either implement or remove from docs |
+| Install URLs | **high** | Inconsistent URLs: `apiad.github.io/starter` vs `apiad.github.io/opencode` | `docs/index.md:39`, `docs/deploy.md:76-91` | Standardize to `apiad.github.io/opencode` |
+| CLI Name | **high** | Docs reference `gemini` CLI but actual CLI is `opencode` | `docs/deploy.md:146,157` | Replace all `gemini` with `opencode` |
+| Wrong Install Flag | **medium** | `docs/deploy.md` shows `--mode=link` but install.sh uses `--link` | `docs/deploy.md:76,79` | Update to match actual flag syntax |
+| Agent-Command Mismatch | **medium** | `design.md` shows agents not in commands, e.g., `query`, `write`, `review` | `docs/design.md:7-17` | Document actual commands or reconcile |
+| Missing `/revise` | **low** | Referenced as "legacy" but implementation unclear | `docs/user-guide.md:227` | Clarify if this command exists |
+
+### Technical Debt
+
+1. **Orphaned Plans** — Multiple `.knowledge/plans/` files for features that may not be implemented:
+   - `add-brainstorm-command.md` — `/brainstorm` not implemented
+   - `implement-learn-command.md` — `/learn` not implemented
+   - `implement-maintenance-v2.md` — `/maintenance` not implemented
+
+2. **Outdated Terminology**
+   - "Tier Protocol" in `docs/index.md:49` — no corresponding implementation
+   - "Context Minifier" in `docs/develop.md:75` and `docs/user-guide.md:18` — no documented implementation
+
+3. **Install Script Issues**
+   - Uses `--link` but docs show `--mode=link` and `--mode=copy`
+   - `REPO_URL` points to `opencode-core` but should document which repo
+
+---
+
+## Recommendations
+
+### Priority 1: Fix Critical Path Issues
+
+1. **Update install URL everywhere** to `https://apiad.github.io/opencode/install.sh`
+   - `docs/index.md:39`
+   - `docs/deploy.md:76,79,91`
+   - `docs/updating.md:14,26,40,52,62,122,156`
+
+2. **Replace CLI name** `gemini` → `opencode` in:
+   - `docs/deploy.md:146,157`
+   - Any other occurrences
+
+3. **Fix `--mode=` → `--link`/`--copy`** in `docs/deploy.md:76-79` and `docs/updating.md`
+
+4. **Update directory structure** in `docs/design.md:115-127`:
+   ```diff
+   - plans/               # Saved execution plans
+   - journal/             # Daily journal entries (YYYY-MM-DD.yaml)
+   - research/           # Research artifacts
+   - drafts/             # Content drafts
+   + .knowledge/
+   + ├── plans/          # Saved execution plans
+   + ├── notes/          # Research artifacts and notes
+   + ├── log/            # Daily journal entries (YYYY-MM-DD.yaml)
+   + └── drafts/        # Content drafts
+   ```
+
+### Priority 2: Reconcile Command Inventory
+
+5. **Decision needed:** Should these commands be implemented or removed from docs?
+   - `/maintenance` — mentioned in multiple docs
+   - `/document` — referenced in develop.md, user-guide.md
+   - `/brainstorm` — has a plan file
+   - `/cron` — mentioned in user-guide.md
+   - `/learn` — has a plan file
+
+### Priority 3: Cleanup
+
+6. Remove or archive orphaned plan files for unimplemented commands
+7. Remove or clarify "Tier Protocol" and "Context Minifier" mentions if no implementation
+8. Add `docs/install.sh` usage examples to match actual `--link` flag
+
+---
+
+## Evidence
+
+### Files Referencing Non-Existent Commands
+- `docs/develop.md:19` — `/maintenance`
+- `docs/develop.md:84-106` — `/learn`
+- `docs/user-guide.md:58-66` — `/learn`
+- `docs/user-guide.md:38-44` — `/brainstorm`
+- `docs/user-guide.md:224-232` — `/review`
+- `docs/user-guide.md:240-252` — `/cron`, `/maintenance`
+- `docs/index.md:48` — `/learn`
+- `docs/index.md:53` — `/document`
+
+### Install URL Inconsistency
+```bash
+# docs/index.md:39
+curl -fsSL https://apiad.github.io/starter/install.sh | bash
+
+# docs/deploy.md:91  
+curl -fsSL https://apiad.github.io/starter/install.sh | bash
+
+# README.md:19
+curl -fsSL https://apiad.github.io/opencode/install.sh | bash
+```

docs/deploy.md

@@ -1,6 +1,6 @@
 # Installation & Setup
 
-Getting the **Gemini CLI Opinionated Framework** up and running is an automated, interactive process. Whether you're starting a new project or integrating into an existing one, the `install.sh` script is your primary tool.
+Getting the **OpenCode Framework** up and running is an automated, non-interactive process. Whether you're starting a new project or integrating into an existing one, the `install.sh` script is your primary tool.
 
 ## Installation Modes
 
@@ -73,13 +73,13 @@ To switch modes, run the installer with the desired mode:
 
 ```bash
 # Copy to Link
-curl -fsSL https://apiad.github.io/opencode/install.sh | bash -s -- --mode=link
+curl -fsSL https://apiad.github.io/opencode/install.sh | bash -s -- --link
 
 # Link to Copy
-curl -fsSL https://apiad.github.io/opencode/install.sh | bash -s -- --mode=copy
+curl -fsSL https://apiad.github.io/opencode/install.sh | bash -s -- --copy
 ```
 
-The installer will prompt for confirmation when switching modes.
+The installer runs non-interactively; use `--link` or `--copy` to specify the mode.
 
 ---
 
@@ -88,7 +88,7 @@ The installer will prompt for confirmation when switching modes.
 The fastest way to install or update the framework is to run the following command:
 
 ```bash
-curl -fsSL https://apiad.github.io/starter/install.sh | bash
+curl -fsSL https://apiad.github.io/opencode/install.sh | bash
 ```
 
 ### 1. New Project (Scaffolding)
@@ -97,7 +97,7 @@ Running `install.sh` in an empty directory will:
 
 - Initialize a fresh Git repository.
 - Extract the core `.opencode/` framework and configuration files.
-- Create the standard project structure (`journal/`, `plans/`, `research/`, `drafts/`).
+- Create the standard project structure (`.knowledge/log/`, `.knowledge/plans/`, `.knowledge/notes/`, `.knowledge/drafts/`).
 - Initialize baseline files (`README.md`, `CHANGELOG.md`, `tasks.yaml`, `makefile`).
 - Perform an initial "feat" commit.
 
@@ -111,15 +111,15 @@ If run inside an existing project, the script performs a **Surgical Update**:
     - `opencode.json`
     - `.opencode/style-guide.md`
 - **Confirm:** Presents a detailed summary of which files will be **created**, **updated**, or **protected** and waits for your approval.
-- **Integrate:** Adds missing directory structures (`journal/`, `plans/`, etc.) if they don't exist.
+- **Integrate:** Adds missing directory structures (`.knowledge/log/`, `.knowledge/plans/`, etc.) if they don't exist.
 - **Commit:** Automatically creates a descriptive `chore` commit marking the update.
 
 ## 🛠️ Prerequisites & Setup
 
 To ensure full functionality, your environment should have:
 
 - **Git:** Required for state management and change detection hooks.
-- **Node.js:** Necessary for running the `gemini` CLI.
+- **Node.js:** Necessary for running the `opencode` CLI.
 - **Python 3.12+:** Required for executing the project's automation scripts in `.opencode/tools/`.
 - **uv:** The required Python package and project manager.
 - **Make:** Used for project validation and health checks (runs `uv run pytest`).
@@ -143,20 +143,20 @@ Once the installation is complete, follow these steps to orient yourself:
 Execute the `/onboard` command to get a high-signal overview of the repository's architecture, standards, and current roadmap.
 
 ```bash
-gemini /onboard
+opencode /onboard
 ```
 
 ### 2. Initialize the Roadmap
 
-Check the current `tasks.yaml` file and use the `/task` command to define your project's initial goals.
+Check the current task list and use the `/todo` command to define your project's initial goals.
 
 ### 3. Start a New Feature
 
 For your first feature, follow the standard workflow:
 
-- **Research:** `gemini /research [topic]`
-- **Plan:** `gemini /plan` (follow the interactive prompts)
-- **Implement:** Begin coding once the plan is saved in `plans/`.
+- **Research:** `opencode /research [topic]`
+- **Plan:** `opencode /plan` (follow the interactive prompts)
+- **Implement:** Begin coding once the plan is saved in `.knowledge/plans/`.
 
 ---
 

docs/design.md

@@ -1,31 +1,28 @@
 # Architecture & Systems
 
-The **Gemini CLI Opinionated Framework** uses **OpenCode** as its agent orchestration layer. The core framework resides in the `.opencode/` directory.
+The **OpenCode Framework** uses **OpenCode** as its agent orchestration layer. The core framework resides in the `.opencode/` directory.
 
 ## 🏗️ The OpenCode Architecture
 
-### Primary Agents (`.opencode/agents/`)
+### Primary Agents (Modes)
 
 | Agent | Purpose |
 |-------|---------|
-| `plan` | Planning workflow - analyzes codebase, generates plans to `plans/` |
-| `build` | TCR coding workflow - manages tasks and delegates to builder |
-| `query` | Default agent for repo Q&A - invokes subagents as needed |
-| `research` | Research campaigns - parallel scout work with writer summaries |
-| `brainstorm` | Critical thinking and risk assessment |
-| `write` | Prose composition and refinement |
-| `review` | Multi-phase editorial review |
+| `analyze` | Research, investigation, and audits |
+| `plan` | Strategy and architectural design |
+| `build` | TCR implementation discipline |
+| `release` | Publishing and versioning |
 
-### Subagents (`.opencode/agents/subagents/`)
+### Subagents
 
 | Subagent | Purpose |
 |----------|---------|
-| `builder` | TCR grunt coding (test-driven implementation) |
-| `scout` | Web research (parallelizable) |
 | `investigator` | Codebase architectural analysis |
-| `writer` | Prose refinement |
-| `reviewer` | Editorial audits |
-| `debugger` | RCA investigation |
+| `scout` | Web research (parallelizable) |
+| `tester` | Hypothesis validation |
+| `drafter` | Content creation |
+| `critic` | Prose review |
+| `general` | General-purpose coding tasks | |
 
 ### Commands (`.opencode/commands/`)
 
@@ -34,31 +31,31 @@ Commands define structured, multi-phase workflows that automate the development
 | Command | Phase | Description |
 |---------|-------|-------------|
 | `/research` | Discovery | Deep-dive exploration producing Markdown reports |
-| `/maintenance` | Discovery | Non-destructive codebase audit |
-| `/review` | Discovery | Multi-phase linguistic and structural audit |
+| `/audit` | Discovery | Codebase audit for tech debt and architecture |
 | `/debug` | Discovery | Scientific, hypothesis-driven forensic investigation |
-| `/brainstorm` | Discovery | Interactive critical-thinking sessions |
+| `/investigate` | Discovery | Root cause analysis |
 | `/plan` | Strategy | Mandatory bridge to execution plans |
-| `/task` | Execution | TCR loop and feature branch isolation |
-| `/draft` | Execution | Content transformation into finished documents |
-| `/document` | Execution | Documentation synchronization |
+| `/build` | Execution | TCR loop implementation |
+| `/fix` | Execution | Bug fix with regression prevention |
+| `/draft` | Execution | Content creation into finished documents |
 | `/onboard` | All | Project orientation for new developers |
 | `/scaffold` | All | Project initialization with modern tooling |
 | `/commit` | Shipping | Conventional commits with grouped changes |
 | `/release` | Shipping | Version bump, changelog, git tagging |
-| `/issues` | All | GitHub CLI integration |
+| `/todo` | All | Task management |
+| `/note` | All | Journal entry creation |
 
 ### The Unified Lifecycle Flow
 
 The framework enforces a strict architectural boundary between discovering what to do and actually doing it. Data flows unidirectionally:
 
-1. **Discovery:** `/research`, `/maintenance`, `/review`, `/debug` create read-only artifacts
-2. **Strategy:** `/plan` generates actionable roadmaps in `plans/`
-3. **Execution:** `/task` (code) or `/draft` (prose) perform actual work
+1. **Discovery:** `/research`, `/audit`, `/debug` create read-only artifacts in `.knowledge/notes/`
+2. **Strategy:** `/plan` generates actionable roadmaps in `.knowledge/plans/`
+3. **Execution:** `/build` (code) or `/draft` (prose) perform actual work
 
 ## 🔄 TCR (Test-Commit-Revert) Protocol
 
-The `/task work` command enforces a high-discipline development lifecycle through a strict TCR loop:
+The `/build` command enforces a high-discipline development lifecycle through a strict TCR loop:
 
 1. **Pre-flight Verification:** Ensures a clean `main` branch and passing tests.
 2. **Isolation:** All work occurs on an auto-generated, kebab-case feature branch.
@@ -68,29 +65,17 @@ The `/task work` command enforces a high-discipline development lifecycle throug
    - **Verify:** If the test fails, the agent is allowed **one quick fix**. If it fails again, the change is **automatically reverted** (`git checkout .`), preserving the last known stable state.
 4. **Integration:** Upon completion, the feature branch is merged, the roadmap is updated, and the branch is deleted.
 
-## 📝 Procedural Task Management
-
-The `tasks.yaml` file is managed exclusively via the `task` tool:
+## 📝 Task Management
 
-- **Single source of truth** for project roadmap
-- **State lifecycle:** `add` (Todo) → `start` (In Progress) → `archive` (Done)
-- **Never edit `tasks.yaml` by hand** — always use the task tool
+Tasks are managed via the `todowrite` tool within agent sessions:
 
-!!! warning "Migrating from TASKS.md"
-    If you have an existing `TASKS.md` file, instruct the model to migrate it:
-    ```
-    /task please migrate from @TASKS
-    ```
+- **Visible task list** for both user and agent
+- **State lifecycle:** pending → in_progress → completed
+- **Priority levels:** high, medium, low
 
 ### Usage
 
-```bash
-task list                    # Show all tasks
-task add --label "Feature X" --description "..."
-task start --task-id G.1
-task archive --task-id G.1
-task attach-plan --task-id G.1 --plan-path plans/my-plan.md
-```
+Use the `/todo` command or `todowrite` tool directly to manage tasks.
 
 ## 🔍 Scientific Debugging (`/debug`)
 
@@ -112,18 +97,21 @@ The framework uses a timestamp-based git hook to enforce journaling:
 ## 📁 Directory Structure
 
 ```
-.opencode/
+.opencode/            # Framework runtime (agents, commands, tools)
 ├── agents/          # Primary agent definitions
 │   └── subagents/  # Specialized subagents
 ├── commands/        # High-level commands
-├── tools/           # Utilities (TypeScript tools: task.ts, journal.ts, pre-commit.py)
-└── style-guide.md   # Prose style rules
-
-plans/               # Saved execution plans
-journal/             # Daily journal entries (YYYY-MM-DD.yaml)
-research/           # Research artifacts
-drafts/             # Content drafts
-tasks.yaml          # Project roadmap (managed by task tool)
+├── tools/           # Utilities (pre-commit.py, etc.)
+├── style-guide.md   # Prose style rules
+└── README.md        # Framework self-documentation
+
+.knowledge/
+├── plans/           # Saved execution plans
+├── notes/           # Research artifacts and analysis notes
+├── log/             # Daily journal entries (YYYY-MM-DD.yaml)
+└── drafts/          # Content drafts
+
+tasks.yaml           # Project roadmap (managed by task tool)
 ```
 
 ## ⚙️ Technology Stack