darkroomengineering · arzafran · Jun 2, 2026 · Jun 2, 2026 · Jun 2, 2026 · Jun 2, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -325,32 +325,30 @@ Use this table to decide where a piece of knowledge belongs:
 | Personal workflow preference ("I want terse responses") | auto-memory (`user` or `feedback`) |
 | Active project state, deadlines, blockers | auto-memory (`project`) |
 | Pointer to external system (Linear board, dashboard URL) | auto-memory (`reference`) |
-| Architecture decision the team must follow | **GitHub Project** (`gh project item-create`) |
-| Library gotcha that affects everyone | **GitHub Project** (`gh project item-create`) |
-| Convention ("All API routes return `{ data, error }`") | **GitHub Project** (`gh project item-create`) |
-| Incident postmortem worth team awareness | **GitHub Project** (`gh project item-create`) |
+| Architecture decision the team must follow | **team-knowledge repo** (`/share-learning`) |
+| Library gotcha that affects everyone | **team-knowledge repo** (`/share-learning`) |
+| Convention ("All API routes return `{ data, error }`") | **team-knowledge repo** (`/share-learning`) |
+| Incident postmortem worth team awareness | **team-knowledge repo** (`/share-learning`) |
 
-**Rule of thumb:** if another team member's AI agent would benefit from knowing it, post it to the GitHub Project. Otherwise let auto-memory handle it.
+**Rule of thumb:** if another team member's AI agent would benefit from knowing it, post it to the team-knowledge repo. Otherwise let auto-memory handle it.
 
 Examples of team-wide entries:
 ```bash
+# Read: browse index or search across notes
+cat $KNOWLEDGE_REPO_PATH/INDEX.md
+rg "smooth-scroll" $KNOWLEDGE_REPO_PATH/
+
 # Architecture decision
-gh project item-create "$KNOWLEDGE_PROJECT_NUMBER" --owner darkroomengineering \
-  --title "decision: Lenis over native smooth-scroll" \
-  --body "Cross-browser consistency. Native smooth-scroll diverges on Safari/Firefox; Lenis normalizes inertia + delta math. See ADR-007."
+/share-learning decision "Lenis over native smooth-scroll for cross-browser consistency"
 
 # Team convention
-gh project item-create "$KNOWLEDGE_PROJECT_NUMBER" --owner darkroomengineering \
-  --title "convention: API response shape" \
-  --body "All API routes return { data, error } — never throw to the caller."
+/share-learning convention "All API routes return { data, error } — never throw to the caller"
 
 # Cross-cutting gotcha
-gh project item-create "$KNOWLEDGE_PROJECT_NUMBER" --owner darkroomengineering \
-  --title "gotcha: Sanity UTC dates" \
-  --body "Sanity API returns UTC dates — always convert to local before display."
+/share-learning gotcha "Sanity API returns UTC dates — always convert to local before display"
 ```
 
-See `docs/knowledge-system.md` for full setup instructions and `gh api graphql` recall patterns.
+See `docs/knowledge-system.md` for full setup instructions and recall patterns.
 
 ## Self-Evolving Learnings (agent convention)
 
@@ -369,7 +367,7 @@ Categories: [categories vary per agent]
 
 This project uses a two-tier knowledge system:
 
-**Shared (Team)** — Stored in the project's GitHub Project board. Architecture decisions, team conventions, cross-cutting gotchas. Accessible to any team member's AI agent via `gh` CLI.
+**Shared (Team)** — Stored in the team-knowledge repo (`darkroomengineering/team-knowledge`). Architecture decisions, team conventions, cross-cutting gotchas. Accessible to any team member's AI agent via `rg`/`cat` on a local clone or via `gh api`.
 
 **Local (Personal)** — Stored in auto-memory and local config files. Workflow preferences, individual learnings, session context. Private to each developer.
 

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,13 @@ All notable changes to cc-settings are documented here.
 
 ## [Unreleased]
 
+### Changed
+
+- **Shared team-knowledge migrated from GitHub Project #7 to a markdown repo** (`darkroomengineering/team-knowledge`). The board was structurally hostile to its primary consumers (agents): network-gated GraphQL reads, not greppable offline, and no linter-enforced structure — `gh project item-create` never set the `Kind` field, so every `/share-learning` post landed `kind: None` and was invisible to a Kind-filtered query. The repo is one note per file + a generated `INDEX.md`, mirroring the local auto-memory tier. Decision + roadmap: `docs/plans/knowledge-repo-migration.md` (weighted comparison scored repo 795 vs board 515).
+  - **New** — `src/schemas/knowledge.ts` (zod frontmatter contract: `name`/`kind`/`tags`/`added-by`/`supersedes`), `src/lib/lint-knowledge.ts` + `src/scripts/lint-knowledge.ts` (`bun run lint:knowledge`), `src/scripts/new-note.ts` (`bun run new-note`), `tests/lint-knowledge.test.ts`, emitted `schemas/knowledge.schema.json`.
+  - **Changed** — `/share-learning` now reads `INDEX.md` for dedup and writes notes via `gh api` (was `gh project item-list`/`item-create`); `docs/knowledge-system.md`, the `AGENTS.md` Knowledge Routing section, and assorted docs retargeted; env `KNOWLEDGE_PROJECT_NUMBER` → `KNOWLEDGE_REPO`.
+  - **Companion** — darky's `search_team_knowledge` reader rewritten for the repo substrate (darkroom-os#18); env `DARKY_KNOWLEDGE_PROJECT_NUMBER` → `DARKY_KNOWLEDGE_REPO`.
+
 ## [11.16.0] — 2026-06-02
 
 Two additions: a **deslop advisory probe** in the proof-of-work gate (the framework-agnostic sibling to react-doctor), and a shift to **PR-by-default** as the standard workflow (with a repo PR template that dogfoods the plain-English standard).

diff --git a/CLAUDE-FULL.md b/CLAUDE-FULL.md
@@ -102,7 +102,7 @@ Scope: consumer hardware and platform-integration questions specifically. Librar
 - **TLDR** (token-efficient codebase exploration via `llm-tldr`) — see `docs/tldr-cheatsheet.md`
 - **Hooks** (29 events, 8 categories, conditional `if` filtering) — see `docs/hooks-reference.md`
 - **Agent frontmatter** (`tools`, `disallowedTools`, `maxTurns`, `permissionMode`, `effort`, `isolation`, `hooks`, `mcpServers`, `initialPrompt`) — see `docs/frontmatter-reference.md`
-- **Knowledge system** (shared GitHub Project board + local auto-memory) — see `docs/knowledge-system.md`
+- **Knowledge system** (shared team-knowledge repo + local auto-memory) — see `docs/knowledge-system.md`
 - **Agent teams** (parallel independent workstreams, `teammateMode: "auto"`) — see `docs/feature-agents-guide.md`
 
 Skill matching is handled by the native `Skill` tool (v2.1.108).

diff --git a/MANUAL.md b/MANUAL.md
@@ -289,7 +289,7 @@ Triggers `/consolidate` — audits rules, skills, and learnings for contradictio
 
 ### Store a Learning
 
-Say: *"remember this"* — the auto-memory system in `~/.claude/CLAUDE.md` captures personal notes automatically (types: `user`, `feedback`, `project`, `reference`). For team-wide gotchas, decisions, and conventions: post directly with `gh project item-create` (see `AGENTS.md` Knowledge Routing section) or describe what to share and the agent will format and post it.
+Say: *"remember this"* — the auto-memory system in `~/.claude/CLAUDE.md` captures personal notes automatically (types: `user`, `feedback`, `project`, `reference`). For team-wide gotchas, decisions, and conventions: use `/share-learning` (see `AGENTS.md` Knowledge Routing section) or describe what to share and the agent will format and post it to the team-knowledge repo.
 
 ### Fetch Docs & Check Versions
 

diff --git a/USAGE.md b/USAGE.md
@@ -199,15 +199,16 @@ Use TLDR when files are large or you need meaning-based search. Use Read/Grep fo
 ### Shared (Team Knowledge Base)
 
 ```bash
-# Store to the project's GitHub Project board
-/learn store --shared gotcha "Biome ignores .mdx files by default"
-/learn store --shared decision "Chose Lenis over native smooth-scroll"
+# Post to the team-knowledge repo (handles dedup automatically)
+/share-learning gotcha "Biome ignores .mdx files by default"
+/share-learning decision "Chose Lenis over native smooth-scroll"
 
-# Recall shared knowledge
-/learn recall shared
+# Recall shared knowledge (requires local clone at $KNOWLEDGE_REPO_PATH)
+cat $KNOWLEDGE_REPO_PATH/INDEX.md
+rg "biome" $KNOWLEDGE_REPO_PATH/
 ```
 
-See `docs/knowledge-system.md` for GitHub Projects setup.
+See `docs/knowledge-system.md` for setup.
 
 ---
 

diff --git a/docs/github-workflow.md b/docs/github-workflow.md
@@ -136,7 +136,7 @@ Use Projects for the big picture. Use Issues for the actual plan. Don't conflate
 | `/project` | Reads linked issue on session start, updates on end |
 | `/create-handoff` | Posts progress comment on linked issue |
 | `/resume-handoff` | Reads linked issue as primary context source |
-| `/share-learning` | Stores team knowledge in GitHub Project board |
+| `/share-learning` | Stores team knowledge in the team-knowledge repo |
 | `/build`, `/fix` | Can reference issue tasks for scope |
 
 ---

diff --git a/docs/knowledge-system.md b/docs/knowledge-system.md
@@ -8,7 +8,7 @@ Two-tier knowledge management for AI-assisted development teams.
 
 | Tier | Storage | Scope | Access |
 |------|---------|-------|--------|
-| **Shared** | GitHub Project board | Team-wide | `gh api graphql` |
+| **Shared** | team-knowledge repo | Team-wide | `gh api` + `rg` |
 | **Local** | Auto-memory + learnings | Per-developer | File system |
 
 **Shared knowledge** is for things the whole team benefits from knowing — architecture decisions, cross-cutting gotchas, resolved incidents, team conventions.
@@ -17,27 +17,43 @@ Two-tier knowledge management for AI-assisted development teams.
 
 ---
 
-## Shared Knowledge (GitHub Projects)
+## Shared Knowledge (team-knowledge repo)
 
 ### Setup
 
-1. Create a GitHub Project on your repository:
-   - Name: `Knowledge Base` (or similar)
-   - Add custom fields:
-     - **Kind** (single select): `decision`, `convention`, `gotcha`, `incident`, `pattern` — name it `Kind`, **not** `Type`; GitHub reserves the field name `Type`. The agent flow keys off the `<kind>:` title prefix regardless, so this field is for board grouping/filtering.
-     - **Tags** (text): free-form tags like `auth`, `api`, `css`, `performance`
-     - **Added By** (text): who added it
+The shared corpus lives at `darkroomengineering/team-knowledge`. One markdown file per note, plus a generated `INDEX.md`.
 
-2. Note the Project number (visible in the URL: `github.com/orgs/ORG/projects/NUMBER`)
+**For `/share-learning` (write path):** no local clone needed — the skill writes via `gh api`. Set the repo slug in your environment if you want to override the default:
+```
+KNOWLEDGE_REPO=darkroomengineering/team-knowledge
+```
+
+**For dev CLIs (`bun run lint:knowledge`, `bun run new-note`):** these tools operate on a local clone. Point them at it:
+```
+KNOWLEDGE_REPO_PATH=/path/to/your/clone/of/team-knowledge
+```
+
+Clone once with:
+```bash
+git clone https://github.com/darkroomengineering/team-knowledge ~/team-knowledge
+```
 
-3. Add to your project's `CLAUDE.local.md` or environment:
-   ```
-   Knowledge base: gh project #NUMBER on ORG/REPO
-   ```
+### Note frontmatter contract
+
+```
+---
+name: <kebab-case slug; equals filename without .md>
+kind: decision | convention | gotcha | incident | pattern
+tags: [kebab, strings]        # optional
+added-by: <github login or name>
+supersedes: <name>            # optional
+---
+<body: what + why + how to apply>
+```
 
 ### What Goes in Shared Knowledge
 
-| Type | Example |
+| Kind | Example |
 |------|---------|
 | `decision` | "Chose Lenis over native smooth-scroll for cross-browser consistency" |
 | `convention` | "All API routes return `{ data, error }` shape" |
@@ -47,37 +63,38 @@ Two-tier knowledge management for AI-assisted development teams.
 
 ### Agent Usage
 
-**Reading shared knowledge:**
+**Reading shared knowledge (agents on dev machines):**
 ```bash
-# List all entries
-gh project item-list NUMBER --owner ORG --format json
+# Browse the index
+cat $KNOWLEDGE_REPO_PATH/INDEX.md
+
+# Search across all notes
+rg "biome" $KNOWLEDGE_REPO_PATH/
 
-# AI agents can query this on session start or when exploring a new area
+# Read a specific note
+cat $KNOWLEDGE_REPO_PATH/biome-mdx-ignored.md
 ```
 
 **Adding shared knowledge:**
 ```bash
-# Via the share-learning skill
+# Via the share-learning skill (preferred — handles dedup + gh api write)
 /share-learning gotcha "Biome ignores .mdx files by default"
-
-# Manually via gh CLI
-gh project item-create NUMBER --owner ORG --title "gotcha: Biome ignores .mdx" --body "Add .mdx to biome.json includes array"
 ```
 
 ### Consumers
 
-Two kinds of agents read this board:
+Two kinds of agents read this corpus:
 
-- **Dev-machine agents** (Claude Code) — read with the `gh project item-list` command above and post via `/share-learning`, which dedups against the board before creating an item.
-- **darky** (the studio Slack bot) — reads the board **on-demand** through its `search_team_knowledge` tool (GraphQL `organization{projectV2}`), gated to questions that touch a team convention/decision/gotcha rather than fulltime ingestion. Wired in [darky PR #474](https://github.com/darkroomengineering/darky/pull/474); requires `DARKY_KNOWLEDGE_PROJECT_NUMBER` in darky's environment. darky keeps its own internal knowledge brain (`search_knowledge`) separate — this board is the cross-studio tier only.
+- **Dev-machine agents** (Claude Code) — read via `cat INDEX.md` + `rg` across a local clone of the repo and post via `/share-learning`, which fetches INDEX.md for dedup before writing via `gh api`.
+- **darky** (the studio Slack bot, now in `darkroomengineering/darkroom-os` under `darky-hermes/`; standalone `darky` repo frozen 2026-06-01) — reads team-knowledge **on-demand** via the GitHub REST contents API, gated to questions that touch a team convention/decision/gotcha.
 
 ### Best Practices
 
-- Keep entries atomic — one learning per entry
+- Keep notes atomic — one learning per file
 - Include the **why**, not just the **what**
 - Add tags for discoverability
-- Review periodically — remove outdated entries
-- If a gotcha gets fixed upstream, archive the entry
+- Review periodically — remove outdated notes
+- If a gotcha gets fixed upstream, supersede the note with a new one
 
 ---
 
@@ -135,17 +152,11 @@ the team-wide tier (above).
 
 ```bash
 # Architecture decision
-gh project item-create "$KNOWLEDGE_PROJECT_NUMBER" --owner darkroomengineering \
-  --title "decision: Lenis over native smooth-scroll" \
-  --body "Cross-browser consistency. Native smooth-scroll diverges on Safari/Firefox; Lenis normalizes inertia + delta math. See ADR-007."
+/share-learning decision "Lenis over native smooth-scroll for cross-browser consistency"
 
 # Team convention
-gh project item-create "$KNOWLEDGE_PROJECT_NUMBER" --owner darkroomengineering \
-  --title "convention: API response shape" \
-  --body "All API routes return { data, error } — never throw to the caller. Enforced by Biome rule in services/api/."
+/share-learning convention "All API routes return { data, error } — never throw to the caller"
 
 # Cross-cutting gotcha
-gh project item-create "$KNOWLEDGE_PROJECT_NUMBER" --owner darkroomengineering \
-  --title "gotcha: Sanity UTC dates" \
-  --body "Sanity API returns UTC dates — always convert to local before display. Affects all date renderers."
+/share-learning gotcha "Sanity API returns UTC dates — always convert to local before display"
 ```
diff --git a/package.json b/package.json
@@ -22,6 +22,8 @@
     "compose": "bun -e 'import { composeSettings } from \"./src/lib/compose-settings.ts\"; console.log(JSON.stringify(await composeSettings(\".\"), null, \"\\t\"))'",
     "check:cli-tools": "bun src/scripts/check-cli-tools.ts",
     "new-skill": "bun src/scripts/new-skill.ts",
+    "lint:knowledge": "bun src/scripts/lint-knowledge.ts",
+    "new-note": "bun src/scripts/new-note.ts",
     "proof": "bun src/scripts/proof.ts",
     "review-batch": "bun src/scripts/review-batch.ts"
   },

diff --git a/schemas/knowledge.schema.json b/schemas/knowledge.schema.json
@@ -0,0 +1,42 @@
+{
+  "$id": "https://raw.githubusercontent.com/darkroomengineering/cc-settings/main/schemas/knowledge.schema.json",
+  "title": "Darkroom knowledge note frontmatter",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+    },
+    "kind": {
+      "type": "string",
+      "enum": [
+        "decision",
+        "convention",
+        "gotcha",
+        "incident",
+        "pattern"
+      ]
+    },
+    "tags": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "added-by": {
+      "type": "string",
+      "minLength": 1
+    },
+    "supersedes": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "name",
+    "kind",
+    "added-by"
+  ],
+  "additionalProperties": {}
+}
diff --git a/skills/README.md b/skills/README.md
@@ -95,7 +95,7 @@ These fork context for clean exploration:
 
 ### The `share-learning` Skill (Manual, Team-Only)
 
-This skill posts architectural decisions, cross-cutting gotchas, and conventions to the shared GitHub Project board so other team members' AI agents pick them up on session start. Invoke it manually or follow the `promote-memory` hook nudge that fires when a `project` or `feedback` auto-memory is written.
+This skill posts architectural decisions, cross-cutting gotchas, and conventions to the shared team-knowledge repo so other team members' AI agents can find them via `rg`/`cat` on a local clone. Invoke it manually or follow the `promote-memory` hook nudge that fires when a `project` or `feedback` auto-memory is written.
 
 For personal notes, the cc-settings auto-memory system (stored under `~/.claude/projects/<hash>/memory/`) captures them automatically. See the "auto memory" section of `~/.claude/CLAUDE.md` for how that works. The rule of thumb: if another team member's AI agent would benefit from knowing it, use `/share-learning`; otherwise let auto-memory handle it.
 

diff --git a/skills/fix/SKILL.md b/skills/fix/SKILL.md
@@ -22,7 +22,7 @@ You are in **Maestro orchestration mode**. Delegate immediately to specialized a
 3. **Diagnose** - Analyze findings to identify root cause
 4. **Implement** - Spawn `implementer` agent to fix the issue
 5. **Verify** - Spawn `tester` agent to confirm the fix
-6. **Learn** - If this was a non-obvious fix, the auto-memory system in `~/.claude/CLAUDE.md` captures it; for team-wide gotchas use `/share-learning` to post to the GitHub Project board
+6. **Learn** - If this was a non-obvious fix, the auto-memory system in `~/.claude/CLAUDE.md` captures it; for team-wide gotchas use `/share-learning` to post to the team-knowledge repo
 
 ## Scope Rules