chore: align opencode memory docs with .memory project

.config/opencode/.gitignore

@@ -0,0 +1,6 @@
+node_modules
+package.json
+bun.lock
+.megamemory/
+.memory/
+.worktrees/

.config/opencode/AGENTS.md

@@ -9,9 +9,9 @@ permalink: opencode-config/agents
 Memory uses one persistent system: **basic-memory**.
 
 - All persistent knowledge is stored in basic-memory notes, split across a **`main` project** (global/shared) and **per-repo projects** (project-specific).
-- Repo-local `.memory/` files are legacy artifacts and are **not** the active source of truth.
-- Do not create, update, or rely on `.memory/*` for current work tracking.
-- **Migration note:** Existing repo-local `.memory/` directories (or `.memory.legacy/`) in projects are non-authoritative and should be ignored unless you are explicitly migrating historical content into basic-memory. Do not delete them automatically — they may contain useful historical context for one-time migration.
+- The managed per-repo basic-memory project directory is `<repo>/.memory/`.
+- Do not edit managed `.memory/*` files directly; use basic-memory MCP tools for all reads/writes.
+- **Migration note:** Older repo-local memory workflow artifacts (including `.memory.legacy/` and legacy contents from prior workflows) are non-authoritative and should not be edited unless you are explicitly migrating historical content into basic-memory.
 
 ### basic-memory
 
@@ -44,12 +44,12 @@ Every code repository must have its own dedicated basic-memory project. This is
 **Creating a new per-repo project:**
 Use `basic-memory_create_memory_project` (or the equivalent MCP tool) with:
 - `project_name`: a short, kebab-case identifier for the repo (e.g., `opencode-config`, `my-web-app`, `data-pipeline`)
-- `project_path`: the repo's root directory on disk
+- `project_path`: the repo's `.memory/` subdirectory on disk (i.e., `<repo-root>/.memory`)
 
 Example for this repo:
 ```
 project_name: opencode-config
-project_path: /home/alex/dotfiles/.config/opencode
+project_path: /home/alex/dotfiles/.config/opencode/.memory
 ```
 
 **Checking if a project exists:**

.config/opencode/agents/lead.md

@@ -379,4 +379,4 @@ This is a ~30-second mental check, not a full review. If something looks obvious
 - For every completed project change set, documentation must be created or updated.
 - Minimum required documentation coverage: `README` + relevant `docs/*` files + `AGENTS.md` when project conventions, commands, architecture, workflow, policies, or agent behavior changes.
 - **Documentation is a completion gate, not a follow-up task.** Do not declare a task done, ask "what's next?", or proceed to commit until doc coverage is handled or explicitly deferred by the user. Waiting for the user to ask is a failure.
-- **Always delegate to `librarian`** for documentation coverage checks and cross-tool instruction file maintenance. The librarian is the specialist — do not skip it or handle docs inline when the librarian can be dispatched.
+- **Always delegate to `librarian`** for documentation coverage checks and `AGENTS.md` maintenance. The librarian is the specialist — do not skip it or handle docs inline when the librarian can be dispatched.

.config/opencode/agents/librarian.md

@@ -15,7 +15,7 @@ You are the Librarian subagent.
 Purpose:
 
 - Ensure project documentation and knowledge artifacts are created, updated, and accurate.
-- Maintain the instruction file (`AGENTS.md`) and its symlinks.
+- Maintain the instruction file (`AGENTS.md`) as the single source of truth.
 - Keep basic-memory guidance and project notes accurate and useful as the project evolves.
 - Ensure all memory references use the `main` vs per-repo project split correctly.
 
@@ -35,7 +35,7 @@ Maintain `AGENTS.md` as the single source of truth:
 
 - **Update when project knowledge changes**: architecture, conventions, commands, structure
 - **Content should include**: project purpose, tech stack, architecture, conventions, build/test/lint commands, project structure
-- **Verify symlinks exist**: `CLAUDE.md`, `.cursorrules`, `.github/copilot-instructions.md` should all point to `AGENTS.md`
+- **Keep guidance centralized**: repo instruction guidance belongs in `AGENTS.md` only
 - **Do NOT duplicate memory project contents** — instruction file is for "how to work here", not "what we're doing"
 - **Ensure the repo's basic-memory project name is documented** in `AGENTS.md` (e.g., `opencode-config`)
 
@@ -63,4 +63,4 @@ Ensure memory guidance consistently reflects the `main` vs per-repo project spli
 - Summarize documentation changes first.
 - List updated files and why each was changed.
 - Explicitly call out any deferred documentation debt.
-- Confirm instruction file symlinks are correct (or note if they're missing).
+- Confirm repo instruction guidance lives in `AGENTS.md` only.

.config/opencode/commands/bootstrap-memory.md

@@ -19,7 +19,8 @@ so future sessions can resume quickly.
 
 Use `list_memory_projects` to check whether this repo already has a basic-memory
 project. If not, create one with `create_memory_project` using a short kebab-case
-name (e.g., `my-web-app`) and the repo's root directory as `project_path`.
+name (e.g., `my-web-app`) and the repo's `.memory/` subdirectory as `project_path`
+(e.g., `/path/to/repo/.memory`).
 
 All subsequent `write_note`, `search_notes`, and `build_context` calls in this
 command must pass `project="<repo-project-name>"` for project-specific notes, or
@@ -36,9 +37,9 @@ current state prevents duplication and helps you decide what to create vs update
 Run `git ls-files` to understand the project layout, then read `README.md` and
 the highest-signal files for architecture and conventions.
 
-Also check for existing cross-tool instruction files (`AGENTS.md`, `CLAUDE.md`,
-`.cursorrules`, `.github/copilot-instructions.md`) — they may contain project
-knowledge from other tools or team members that should be incorporated.
+Also check whether any legacy tool-specific instruction files exist alongside
+`AGENTS.md` — they may contain project knowledge from other tools or team
+members that should be consolidated into `AGENTS.md`.
 
 Identify:
 - What the project does (primary capabilities)
@@ -81,9 +82,9 @@ Do not store project-specific plans, decisions, or session state in `main`.
 If `AGENTS.md` exists, update it with any new project knowledge discovered
 during bootstrap (architecture, conventions, commands). Add the repo's
 basic-memory project name (e.g., `opencode-config`) to `AGENTS.md` so
-agents know which project to target. The symlinks (`CLAUDE.md`,
-`.cursorrules`, `.github/copilot-instructions.md`) will automatically
-reflect changes.
+agents know which project to target. If legacy tool-specific instruction files
+exist, consolidate any durable repo guidance into `AGENTS.md` and stop
+maintaining duplicate copies.
 
 If the instruction file doesn't exist, note that `/init` should be run to create it.
 
@@ -94,4 +95,4 @@ If the instruction file doesn't exist, note that `/init` should be run to create
 - Prefer durable knowledge over transient status notes.
 - Use WikiLinks `[[Topic]]` to create relations between related notes.
 - Use tags for categorization: `#pattern`, `#convention`, `#decision`, `#architecture`.
-- Always pass the `project` parameter on every MCP call.
+- Always pass the `project` parameter on every MCP call.

.config/opencode/commands/init.md

@@ -47,10 +47,7 @@ Delegate to the `coder` subagent with explicit mode (`new_project` or `existing_
 
 - Required scaffold targets:
   - `README.md` — title, purpose, tech stack, quick-start, project structure overview
-  - `AGENTS.md` — real instruction file containing shared project guidance
-  - `CLAUDE.md` — symlink to `AGENTS.md`
-  - `.cursorrules` — symlink to `AGENTS.md`
-  - `.github/copilot-instructions.md` — symlink to `../AGENTS.md`
+  - `AGENTS.md` — instruction file containing shared project guidance
   - `docs/architecture.md` — stub with title + purpose
   - `.gitignore` — add stack-appropriate ignores (e.g., `node_modules/`, `__pycache__/`, `target/`)
   - other stack-specific scaffold files if clearly implied (e.g., `package.json`, `pyproject.toml`)
@@ -60,14 +57,9 @@ Delegate to the `coder` subagent with explicit mode (`new_project` or `existing_
   - create or fill in only missing pieces
   - **do not overwrite existing files**
   - explicitly instruct coder to check existence before creating each target
-  - ensure `AGENTS.md` exists as the real instruction file
-  - create missing symlinks:
-    - `ln -s AGENTS.md CLAUDE.md`
-    - `ln -s AGENTS.md .cursorrules`
-    - `ln -s ../AGENTS.md .github/copilot-instructions.md`
-  - if `AGENTS.md` is missing but `.github/copilot-instructions.md` exists as a real file, move its content into `AGENTS.md`, then recreate `.github/copilot-instructions.md` as a symlink
+  - ensure `AGENTS.md` exists as the project instruction file
+  - if legacy tool-specific instruction files exist, consolidate any repo-specific guidance into `AGENTS.md` and stop maintaining duplicate copies
   - examples:
-    - if `README.md` exists and only `CLAUDE.md` is missing, create `CLAUDE.md` as a symlink to `AGENTS.md`
     - if `docs/` is missing, create it and add `docs/architecture.md`
 
 ## Step 4 — Documentation review (delegate to `librarian`)
@@ -76,7 +68,7 @@ Always delegate to the `librarian` subagent, for both new and existing projects.
 
 - Ensure `README.md` is accurate and complete for the current project state.
 - Ensure `AGENTS.md` exists and captures project-specific workflow decisions from Step 2.
-- Verify `CLAUDE.md`, `.cursorrules`, and `.github/copilot-instructions.md` are symlinks to `AGENTS.md`.
+- Ensure repo instruction guidance lives in `AGENTS.md` only.
 - Ensure stubs are explicitly marked for later completion.
 - Keep edits additive and non-destructive for existing projects.
 
@@ -84,7 +76,7 @@ Always delegate to the `librarian` subagent, for both new and existing projects.
 
 Always create or update basic-memory project notes for this project.
 
-- **Ensure a dedicated per-repo basic-memory project exists.** Use `list_memory_projects` to check. If not found, create one with `create_memory_project` using a short kebab-case name (e.g., `my-web-app`) and the repo's root directory as `project_path`.
+- **Ensure a dedicated per-repo basic-memory project exists.** Use `list_memory_projects` to check. If not found, create one with `create_memory_project` using a short kebab-case name (e.g., `my-web-app`) and the repo's `.memory/` subdirectory as `project_path` (e.g., `/path/to/repo/.memory`).
 - All subsequent note operations in this step must pass `project="<repo-project-name>"`.
 - Use `search_notes` (with `project`) to check for existing project notes to avoid duplicates.
 - Use `write_note` (with `project`) to create or update a `knowledge/overview` note with:
@@ -114,4 +106,4 @@ Delegate git operations to `coder` based on discovered state.
 Summarize:
 - Files created and files updated, with purpose.
 - Decisions made and decisions deferred.
-- What the user should fill in next (stubs, open questions, follow-up documentation).
+- What the user should fill in next (stubs, open questions, follow-up documentation).

.config/opencode/commands/save-memory.md

@@ -15,7 +15,8 @@ you noticed, or intent the user shared.
 
 Use `list_memory_projects` to find this repo's dedicated basic-memory project.
 If it doesn't exist, create one with `create_memory_project` using a short
-kebab-case name and the repo's root directory as `project_path`.
+kebab-case name and the repo's `.memory/` subdirectory as `project_path`
+(e.g., `/path/to/repo/.memory`).
 
 All project-specific notes must target `project="<repo-project-name>"`.
 Cross-project reusable knowledge must target `project="main"`.
@@ -68,7 +69,7 @@ Report what was added/updated, where, and in which project.
 
 If project `knowledge/` notes were **materially** updated (architecture, conventions,
 commands — not just plans/research), update `AGENTS.md` to reflect the changes.
-The symlinks automatically propagate to all tools.
+Keep repo instruction guidance in `AGENTS.md` only.
 
 If updates were only plans/research/tracking details, skip this step.
 
@@ -80,4 +81,4 @@ If updates were only plans/research/tracking details, skip this step.
 - Keep hierarchy shallow (max 2 heading levels preferred).
 - Be specific. "Handles auth" is weak. "JWT auth with RS256, validated in
   `src/middleware/auth.ts`, refresh tokens in Redis with 7d TTL" is useful.
-- Always pass the `project` parameter on every MCP call.
+- Always pass the `project` parameter on every MCP call.

.config/opencode/decisions/Instruction File Policy.md

@@ -1,18 +0,0 @@
----
-title: Instruction File Policy
-type: note
-permalink: opencode-config/decisions/instruction-file-policy
-tags:
-- instructions
-- convention
----
-
-# Instruction File Policy
-
-## Decision
-- [decision] `AGENTS.md` is the only instruction file maintained in this repo. #convention
-- [decision] Do not create or maintain mirrored instruction files or symlinks for other agent tools. #convention
-- [decision] If a tool needs repo instructions, point it at `AGENTS.md` directly. #convention
-
-## Rationale
-- [lesson] Keeping a single source of truth removes cross-tool instruction maintenance overhead and avoids duplicated or stale guidance. #lesson

.config/opencode/decisions/Memory System Main vs Per-Repo Project Split.md

@@ -1,48 +0,0 @@
----
-title: Memory System Main vs Per-Repo Project Split
-type: note
-permalink: opencode-config/decisions/memory-system-main-vs-per-repo-project-split
-tags:
-- memory
-- convention
-- decision
-- architecture
----
-
-# Memory System: Main vs Per-Repo Project Split
-
-## Decision
-Adopted a strict two-project split for basic-memory:
-- `main` is reserved exclusively for global/shared knowledge (reusable patterns, conventions, tech knowledge, user preferences, cross-project lessons)
-- Each code repository gets its own dedicated basic-memory project for project-specific knowledge (plans, decisions, research, gates, sessions, architecture)
-
-## Observations
-- [decision] `main` is global-only; never store project plans/decisions/research/gates/sessions in `main` #memory #convention
-- [decision] Every repo must have a per-repo basic-memory project created via `create_memory_project` #memory #convention
-- [decision] Session-start protocol requires identifying and selecting the per-repo project before any reads/writes #memory #convention
-- [decision] All MCP calls must pass the `project` parameter explicitly — `project="main"` for global, `project="<repo-project-name>"` for project-specific #memory #convention
-- [decision] Repo-local `.memory/` directories are legacy artifacts, renamed to `.memory.legacy/` #memory
-
-## Affected Files (opencode-config repo)
-- `AGENTS.md` — core memory system section rewritten with main/per-repo split, session-start protocol, project setup instructions
-- `commands/init.md` — Step 5 creates per-repo basic-memory project
-- `commands/bootstrap-memory.md` — Step 0 ensures per-repo project, all steps pass project parameter
-- `commands/save-memory.md` — distinguishes main vs per-repo targets
-- `commands/status.md` — requires per-repo project identification
-- `commands/plan.md` — per-repo project targeting for plans/decisions/research
-- `commands/sme.md` — split guidance caching between main and per-repo
-- `commands/research.md` — split project targeting
-- `commands/review.md` — per-repo project targeting
-- `commands/test.md` — per-repo project targeting
-- `commands/docs.md` — per-repo project targeting
-- `agents/lead.md` — session-start project identification, all note sections updated
-- `agents/sme.md` — explicit main vs per-repo caching workflow
-- `agents/librarian.md` — updated to enforce main/per-repo split in docs
-- `agents/reviewer.md` — per-repo project recording
-- `agents/tester.md` — per-repo project recording
-- `agents/critic.md` — per-repo project recording
-- `agents/designer.md` — per-repo project recording
-- `skills/git-workflow/SKILL.md` — clarified per-repo/main in legacy note
-
-## Relations
-- related_to [[opencode-config Knowledge Overview]]

.config/opencode/gates/Review- Main vs Per-Repo Project Split Consistency.md

@@ -1,33 +0,0 @@
----
-title: 'Review: Main vs Per-Repo Project Split Consistency'
-type: note
-permalink: opencode-config/gates/review-main-vs-per-repo-project-split-consistency
-tags:
-- review
-- memory
-- approved
-- consistency
----
-
-# Review: Main vs Per-Repo Project Split Consistency
-
-## Verdict
-- [decision] APPROVED — all instruction files consistently enforce the main/per-repo basic-memory project split #review #memory
-
-## Scope Reviewed
-- `AGENTS.md` — core memory system section
-- All 10 command files (`commands/*.md`)
-- All 10 agent definition files (`agents/*.md`)
-- All 3 skill files (`skills/*/SKILL.md`)
-- Legacy `.memory.legacy/` directory (confirmed non-authoritative)
-- `decisions/Memory System Main vs Per-Repo Project Split.md` (migration decision note)
-
-## Key Findings
-- [finding] Zero files instruct agents to store project-specific notes in `main` — hard rule at AGENTS.md:32 is consistently enforced #confirmed
-- [finding] Session-start protocol is documented in 6 locations with consistent create-if-missing pattern #confirmed
-- [finding] All `project="main"` references correctly scope to cross-project reusable knowledge only #confirmed
-- [finding] No contradictions between any files — migration decision note lists all affected files, all verified updated #confirmed
-- [finding] Minor precision gap: explorer.md and researcher.md use generic "relevant basic-memory project notes" without explicit project parameter guidance, but behavior is practically correct #suggestion
-
-## Relations
-- related_to [[Memory System Main vs Per-Repo Project Split]]

.config/opencode/skills/doc-coverage/SKILL.md

@@ -25,13 +25,10 @@ For every completed change set, verify documentation coverage:
 
 ### 3. Instruction File
 
-Check `AGENTS.md` and its symlinks:
+Check `AGENTS.md` as the single instruction source:
 
 - Does `AGENTS.md` exist and contain current project info?
-- Do symlinks exist and point correctly?
-  - `CLAUDE.md -> AGENTS.md`
-  - `.cursorrules -> AGENTS.md`
-  - `.github/copilot-instructions.md -> ../AGENTS.md`
+- If legacy tool-specific instruction files exist, has their durable repo guidance been consolidated into `AGENTS.md`?
 - Does the instruction file contain:
   - Project purpose and overview
   - Tech stack and architecture
@@ -41,7 +38,7 @@ Check `AGENTS.md` and its symlinks:
 - Is the instruction file in sync with current project state?
 
 **Anti-patterns:**
-- Symlinks missing or pointing to wrong location
+- Mirrored instruction files requiring parallel maintenance
 - Instruction file is stale or empty
 - Instruction file duplicates basic-memory project note content (plans, research)
 
@@ -69,4 +66,4 @@ Check `AGENTS.md` and its symlinks:
 
 - The **librarian** subagent is the specialist for documentation work.
 - Lead should delegate doc coverage review to librarian after coder completes implementation.
-- Librarian reads the changes, identifies doc gaps, and writes/updates documentation.
+- Librarian reads the changes, identifies doc gaps, and writes/updates documentation.

.config/opencode/skills/git-workflow/SKILL.md

@@ -15,7 +15,7 @@ permalink: opencode-config/skills/git-workflow/skill
    - 1-2 sentences max.
    - Match the repository's existing style.
 5. Check for secrets: do NOT commit `.env`, credentials, or key files.
-6. Repo-local `.memory/` directories are legacy artifacts and should not be relied upon. Do not commit new `.memory/` content — use basic-memory notes (in the per-repo project or `main`) instead.
+6. The managed per-repo basic-memory project directory is `<repo>/.memory/`; do not edit managed `.memory/*` files directly. Older repo-local memory workflow artifacts (including `.memory.legacy/` and legacy contents from prior workflows) are non-authoritative and should not be edited unless explicitly migrating historical content into basic-memory.
 7. Stage relevant files: `git add <files>` (not blindly `git add .`).
 8. Commit: `git commit -m "<message>"`.
 9. Run `git status` after commit to verify success.
@@ -101,4 +101,4 @@ gh issue comment <number> -b "<comment>"  # Add comment
 - **Never `git push --force` to `main`/`master`** unless the user explicitly confirms.
 - **Never skip hooks** (`--no-verify`) unless the user explicitly requests it.
 - **Never `git commit --amend`** unless: (1) explicitly requested OR pre-commit hook auto-modified files, (2) HEAD was created in this session, AND (3) commit has NOT been pushed to remote.
-- If commit fails due to pre-commit hook, fix the issue and create a NEW commit.
+- If commit fails due to pre-commit hook, fix the issue and create a NEW commit.