Best-practice upgrade: memory layer, operating-system pack, deterministic enforcement, exhaustive README

.claude/settings.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR\"/scripts/validate-frontmatter.sh >&2 || exit 2"
+          }
+        ]
+      }
+    ]
+  }
+}

.claude/skills/customer-brief

@@ -0,0 +1 @@
+../../skills/customer-brief

.claude/skills/normalize-meeting

@@ -0,0 +1 @@
+../../skills/normalize-meeting

.claude/skills/update-wiki

@@ -0,0 +1 @@
+../../skills/update-wiki

.claude/skills/weekly-brief

@@ -0,0 +1 @@
+../../skills/weekly-brief

.github/CODEOWNERS

@@ -0,0 +1,14 @@
+# Every canonical change needs a human owner's review. With branch
+# protection requiring code-owner review, this is the deterministic form
+# of "PRs gate the truth."
+#
+# Replace with real handles after instantiating the template.
+
+# Default: the founder owns everything
+* @{{GITHUB_FOUNDER_HANDLE}}
+
+# Sensitive surfaces — keep founder-only even as the team grows
+finance.md @{{GITHUB_FOUNDER_HANDLE}}
+people/ @{{GITHUB_FOUNDER_HANDLE}}
+AGENTS.md @{{GITHUB_FOUNDER_HANDLE}}
+.github/ @{{GITHUB_FOUNDER_HANDLE}}

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,17 @@
+<!-- One idea per PR. Semantic title, e.g.:
+     customer(acme): update renewal status after 2026-04-15 call -->
+
+## What changed
+
+<!-- One or two sentences. Link evidence (meeting note, decision, live source). -->
+
+## Checklist (from guides/OPERATIONS.md → "How PRs should look")
+
+- [ ] Small — one idea, one file (or a tight set)
+- [ ] Frontmatter `updated` + `last_verified` refreshed on touched canonical files
+- [ ] Timeline entries appended, never rewritten (history is immutable)
+- [ ] Links to evidence included
+- [ ] No secrets, no PII, no financials, no NDA content
+- [ ] New canonical files follow their folder README contract (frontmatter, structure)
+- [ ] If this changes standing behavior or process: the relevant doc/SOP updated in this same PR (handbook-first)
+- [ ] Agent-authored commits carry their `Co-Authored-By: <agent>` trailer (provenance)

.github/workflows/validate.yml

@@ -0,0 +1,68 @@
+name: validate
+
+# CI for the intelligence repo. Three checks, all advisory rules made
+# deterministic (prose is advisory; CI guarantees it — see guides/ARCHITECTURE.md):
+#   1. Frontmatter — every canonical file carries the required fields
+#   2. Secrets — gitleaks scan; a leak fails the build
+#   3. Links — no broken relative links between Markdown files
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  frontmatter:
+    name: Frontmatter contract
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Validate frontmatter on canonical files
+        run: bash scripts/validate-frontmatter.sh
+
+  secrets:
+    name: Secret scan (gitleaks)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      # The gitleaks CLI is free for any repo; the GitHub Action wrapper
+      # requires a paid license for organization accounts — so we run the
+      # pinned binary directly.
+      - name: Install gitleaks
+        run: |
+          GITLEAKS_VERSION=8.21.2
+          curl -sSfL "https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/gitleaks_${GITLEAKS_VERSION}_linux_x64.tar.gz" | tar -xz gitleaks
+      - name: Detect secrets
+        run: ./gitleaks detect --source . --redact -v
+
+  links:
+    name: Markdown link check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Check relative links
+        uses: lycheeverse/lychee-action@v2
+        with:
+          # Offline: only verify file-to-file links inside the repo.
+          # External URLs are checked by humans; CI shouldn't fail on a
+          # third-party outage. {{PLACEHOLDER}} links in templates/ are
+          # scaffolding, not real targets — excluded (raw + URL-encoded).
+          # .claude/skills/* are symlinks into skills/ — lychee resolves
+          # their relative links against the symlink path, so the canonical
+          # copies are checked and the symlinked views are skipped.
+          args: --offline --include-fragments --no-progress --exclude '(%7B%7B|\{\{)' --exclude-path '.claude' "**/*.md"
+          fail: true
+
+  stale-report:
+    name: Staleness report (advisory)
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v4
+      - name: Report stale pages (does not fail the build)
+        run: bash scripts/check-stale.sh || true

.gitignore

@@ -26,10 +26,6 @@ meetings/**/*.mp4
 meetings/**/*.wav
 meetings/**/transcripts/
 
-# MkDocs build output
-site/
-.cache/
-
 # Python / Node scratch
 __pycache__/
 *.pyc
@@ -44,8 +40,6 @@ Thumbs.db
 .vscode/settings.json
 .idea/
 *.swp
-.obsidian/workspace.json
-.obsidian/workspace-mobile.json
 
 # Logs
 *.log

AGENTS.md

@@ -43,29 +43,36 @@ If two sources disagree, surface the conflict. Don't guess.
 
 | Folder         | What goes here                                                  |
 |----------------|-----------------------------------------------------------------|
-| (root)         | `company.md`, `strategy.md`, `product.md`, `brand.md`, `ops.md`, `finance.md` |
+| (root)         | `company.md`, `strategy.md`, `product.md`, `brand.md`, `ops.md`, `finance.md`, `legal.md` |
 | `customers/`   | One file per named customer or active prospect                  |
 | `competitors/` | One file per competitor                                         |
-| `people/`      | Team, advisors, partners, investors (one file each)             |
+| `people/`      | Team, freelancers/contractors, advisors, partners, investors (one file each) |
 | `sales/`       | Pipeline by stage; deals worth tracking; pricing                |
 | `decisions/`   | `YYYY-MM-DD-<slug>.md` — append-only ADRs, immutable            |
-| `meetings/`    | `YYYY-MM-DD-<topic>.md` — distilled meeting notes               |
+| `meetings/`    | `<category>/YYYY-MM-DD-<topic>.md` — distilled notes in a per-type folder (standups, leadership, one-on-ones, customers, product, marketing) |
 | `weekly/`      | `YYYY-Www.md` — Friday founder/team brief                       |
+| `management/` | Management-system artifacts: vision, goals, KPIs, accountability, `processes/` (SOPs) |
+| `memory/`      | Agent-operational memory: `MEMORY.md` index, daily worklogs, `learnings.md` |
 | `skills/`      | (Optional) Cross-tool agent skills in SKILL.md format           |
 | `templates/`   | Note templates with frontmatter scaffolding                     |
 
+Infrastructure (not knowledge): `guides/` manuals · `scripts/` validators · `agents-compat/` runtime adapters · `GLOSSARY.md` every term defined. See README's file map.
+
 ---
 
 ## Operating rules
 
 - Prefer **updating** an existing canonical page over creating a new one.
-- One idea per file.
 - Preserve frontmatter. Add `updated` and `last_verified` when you materially change facts.
 - Keep current truth separate from append-only history — **compiled truth above `---`, dated timeline below.**
-- Use wikilinks (`[[customers/acme-co]]`), not repetition.
-- Mark uncertainty explicitly.
+- Use wikilinks (`[[customers/acme-co]]`), not repetition. They resolve **repo-root-relative, no `.md` extension** — an agent navigation convention (GitHub renders them as plain text; see [`GLOSSARY.md`](./GLOSSARY.md)).
+- Mark uncertainty explicitly: tag unconfirmed facts inline with `[VERIFY]` (and reasoned guesses with `[INFERENCE]`). A human confirms → remove the tag, bump `last_verified`.
 - Never depend on chat history for continuity. Write important state to files.
-- **Every non-trivial canonical write opens a PR.** Time-series content (meetings, weekly briefs) can auto-commit.
+- **Handbook-first.** Document the change in this repo, then announce it (Slack/email) with a link to the diff — never the reverse.
+- **Every non-trivial canonical write opens a PR.** Only meeting notes and memory worklogs auto-commit. Weekly briefs always go through a PR with human review — never auto-merge them.
+- When a mistake gets corrected, **write a `memory/learnings.md` entry before finishing the task.**
+- **Codify repetition.** When you notice the same multi-step workflow for the 3rd time, propose a new skill via PR (`skills/README.md` has the contract) — don't keep re-deriving it.
+- **Sign your work.** Semantic commit titles (`customer(acme): update renewal after 2026-04-15 call`) with the *why* in the body, and every agent-authored commit carries a `Co-Authored-By: <Agent> <noreply@…>` trailer naming the agent/runtime. Never impersonate the human — provenance is part of the audit trail.
 
 ---
 
@@ -75,7 +82,7 @@ Every durable note includes:
 
 ```yaml
 ---
-type: customer            # customer | competitor | person | decision | meeting | weekly | strategy | product | brand | company | sales | runbook
+type: customer            # customer | competitor | person | decision | meeting | weekly | strategy | product | brand | company | ops | finance | legal | sales | runbook | vision | goals | kpis | accountability | memory
 status: verified          # draft | active | verified | superseded | archived
 owner: {{FOUNDER_NAME}}
 created: 2026-04-22
@@ -122,6 +129,12 @@ This is what humans and agents see first.>
 
 ---
 
+## Memory
+
+At session start read [`memory/MEMORY.md`](./memory/MEMORY.md) (curated index, always small), then today's and yesterday's `memory/YYYY-MM-DD.md` worklogs. Older worklogs and `memory/learnings.md` load on demand. Memory holds *agent-operational* facts only — company knowledge belongs in the knowledge files. Full contract: [`memory/README.md`](./memory/README.md).
+
+---
+
 ## Preferred outputs
 
 When answering questions or writing content:
@@ -131,6 +144,7 @@ When answering questions or writing content:
 - **Founder-readable** — no jargon unless it's our jargon.
 - **Explicit about confidence** — flag uncertainty.
 - **Linked to evidence** — cite the page or the live source.
+- **English is the operating language.** Compiled truth, summaries, and frontmatter are always English, whatever the source language. Verbatim evidence stays in its original language — quotes, transcript excerpts, local-market brand voice examples. Quote first, summarize in English after.
 
 ---
 
@@ -162,6 +176,8 @@ If an answer required live MCP plus synthesis, **write the durable part back**.
 
 ## If you are unsure
 
+**Precedence on conflict:** the folder README (the specific contract) wins over this file's general rules; this file wins over `guides/`. Surface the conflict in your PR so it gets fixed.
+
 Do the smallest safe thing:
 
 1. Read more files.
@@ -181,4 +197,4 @@ A task is complete when:
 
 ---
 
-*See [`CLAUDE.md`](./CLAUDE.md) for Claude-Code-specific extensions. See [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md) for the rationale behind this structure. If you've been asked to bootstrap an intelligence repo from raw data, read [`docs/DATA-ORGANIZATION-PLAYBOOK.md`](./docs/DATA-ORGANIZATION-PLAYBOOK.md) (routing + root-file contracts) then [`docs/AGENT-INSTRUCTIONS.md`](./docs/AGENT-INSTRUCTIONS.md) (nine-phase procedure). Each folder's `README.md` is the per-file generation contract.*
+*See [`CLAUDE.md`](./CLAUDE.md) for Claude-Code-specific extensions. See [`guides/ARCHITECTURE.md`](./guides/ARCHITECTURE.md) for the rationale behind this structure. If you've been asked to bootstrap an intelligence repo from raw data, read [`guides/DATA-ORGANIZATION-PLAYBOOK.md`](./guides/DATA-ORGANIZATION-PLAYBOOK.md) (routing + root-file contracts) then [`guides/AGENT-INSTRUCTIONS.md`](./guides/AGENT-INSTRUCTIONS.md) (eleven-phase procedure). Each folder's `README.md` is the per-file generation contract.*

CLAUDE.md

@@ -7,10 +7,11 @@ This file adds **Claude-Code-specific** guidance on top of the universal rules i
 ## Read order at session start
 
 1. `AGENTS.md` (loaded via the import above)
-2. `INDEX.md` for a curated map of entry points
-3. If the task is recent-work-related: the most recent file in `weekly/`
-4. If the task touches a specific domain: that root file or folder
-5. Only then use MCP for fresh operational state
+2. `memory/MEMORY.md` + today's and yesterday's `memory/YYYY-MM-DD.md` worklogs **if present** (a fresh repo has none — that's normal)
+3. `INDEX.md` for a curated map of entry points
+4. If the task is recent-work-related: the most recent file in `weekly/`
+5. If the task touches a specific domain: that root file or folder
+6. Only then use MCP for fresh operational state
 
 ## Claude-Code features — when to reach for each
 
@@ -47,6 +48,6 @@ Do not add to `CLAUDE.md`:
 
 ## Local overrides
 
-Personal per-machine overrides (sandbox URLs, local paths, preferred thinking mode) go in `CLAUDE.local.md`. That file is gitignored.
+Personal per-machine overrides (sandbox URLs, local paths, preferred thinking mode) go in `CLAUDE.local.md`. That file is gitignored and optional — Claude Code skips the import silently if it doesn't exist.
 
 @CLAUDE.local.md

CONTRIBUTING.md

@@ -0,0 +1,11 @@
+# Contributing
+
+How changes enter this repo — for humans and agents alike. This page is pointers; the linked contracts govern.
+
+1. **Nobody writes canonical truth to `main`.** Branch → PR → human review → merge. Only meeting notes and memory worklogs auto-commit. ([`AGENTS.md`](./AGENTS.md) § Operating rules)
+2. **One idea per PR**, semantic title (`customer(acme): update renewal after 2026-04-15 call`), the *why* in the body. Agent-authored commits carry a `Co-Authored-By: <agent>` trailer — provenance is part of the audit trail. The PR template carries the full checklist.
+3. **Before opening a PR, run `make verify`** — the same frontmatter/secrets/links checks CI runs. Red CI on a PR? See [`guides/FAQ-AND-FAILURE-MODES.md`](./guides/FAQ-AND-FAILURE-MODES.md).
+4. **Follow the folder contract.** Every folder's `README.md` is the complete spec for files in it (frontmatter, structure, quality bar). On conflict, the folder README wins over general rules.
+5. **Handbook-first.** Change the repo, then announce with a link — never the reverse.
+6. **History is append-only.** Never rewrite a timeline entry or an ADR; correct with a new dated line or a superseding decision.
+7. **Reviewing instead of writing?** The human's job — what to check, how to merge — is one page: [`guides/HUMAN-JOB.md`](./guides/HUMAN-JOB.md).

GLOSSARY.md

@@ -0,0 +1,47 @@
+# Glossary
+
+Every term this repo uses, defined. If a word here is unclear anywhere in the docs, the docs failed — open a PR adding or improving the entry. Two sections: the system's own vocabulary (ships with the template), and your company's terms (you grow it).
+
+## System terms
+
+| Term | Meaning |
+|------|---------|
+| **SSOT** | Single source of truth — each fact lives in exactly one canonical place; everything else links to it. This repo is the company's SSOT. |
+| **Agent** | An AI assistant (Claude Code, OpenClaw, Cursor…) that reads and writes this repo on your behalf. You talk to it; it does the file work. |
+| **PR (pull request)** | GitHub's "proposed change" mechanism: a bundle of edits you review as a diff and accept with the **Merge** button. How all canonical truth enters this repo. See [`guides/HUMAN-JOB.md`](./guides/HUMAN-JOB.md) for the click-by-click. |
+| **Merge** | Accepting a PR — the moment a proposed change becomes truth on `main`. |
+| **CI** | Continuous integration — automated checks that run on every PR (here: frontmatter, secrets, links, staleness). Green check = safe to merge; red = something's wrong. |
+| **Diff** | The before/after view of a change, shown line by line in a PR. |
+| **Frontmatter** | The `--- … ---` block of metadata (type, status, owner, dates) at the top of every durable file. Lets agents route and lets staleness be measured. |
+| **Compiled truth** | The top half of an entity page (above the `---` rule): the current best understanding, rewritten freely as you learn. |
+| **Timeline** | The bottom half of an entity page: dated, append-only history. Never edited, never deleted — corrections are new dated lines. |
+| **ADR** | Architecture decision record — the format `decisions/` files use: context, the decision, consequences, alternatives. Despite the name, used for *any* significant decision, not just technical ones. |
+| **Wikilink** | `[[customers/acme-co]]` — an agent navigation convention pointing at another file, repo-root-relative, no `.md`. GitHub renders them as plain text; agents resolve them. |
+| **MCP** | Model Context Protocol — the standard that lets agents read/write live systems (Slack, Linear, Notion, Granola…) directly. The repo holds durable truth; MCP fetches live state. |
+| **Skill** | A reusable agent procedure in `skills/<name>/SKILL.md`. In Claude Code you invoke one by typing its name as a slash command (e.g. `/weekly-brief`) in the chat. |
+| **Handbook-first** | Document the change in this repo, *then* announce it with a link — never the reverse. |
+| **North-star metric** | The single number the whole company optimizes — defined in `strategy.md`. If it moves, everything is working. |
+| **KPI** | Key performance indicator — one of the 5–15 weekly numbers in `management/kpis.md` (definitions and dashboard links live there; the values stay in dashboards). |
+| **Goal (quarterly)** | One of the 3–7 owned, binary-done quarterly goals in `management/goals.md`. EOS calls these *Rocks*. |
+| **Seat** | A role in `management/accountability.md` with exactly one accountable owner — "when two people are accountable, nobody is." |
+| **EOS** | Entrepreneurial Operating System (Gino Wickman, *Traction*) — one of the frameworks the `management/` pack is compatible with. You don't need to know it. |
+| **L10 / Level 10 Meeting™** | EOS's weekly leadership meeting format: segue (good news) → KPI review → goal review → headlines → to-dos → IDS → conclude. |
+| **IDS** | Identify–Discuss–Solve — EOS's issue-processing method: name the real issue, discuss it once, decide. The point is issues get *solved*, not re-discussed weekly. |
+| **Segue** | The opening minutes of an L10: each person shares one piece of good news. Jargon for "check-in." |
+| **`[VERIFY]`** | Inline tag marking a fact that came from an unconfirmed source (auto-transcription, inference). Anyone who knows the answer confirms it, removes the tag, bumps `last_verified`. `[INFERENCE]` marks a reasoned guess. |
+| **Audit trail** | The automatic record of what changed, why, by whom (human or agent), and when. Git provides it: commits + PR history + the `Co-Authored-By` agent trailer. Readable per file via GitHub's **History**/**Blame** buttons — or by asking the agent. |
+| **Blame** | GitHub's per-line view of who last changed each line of a file and in which commit. Despite the name, it's just attribution. |
+| **Staleness** | How long since a file's `last_verified` date. `scripts/check-stale.sh` flags files past their type's threshold. |
+| **gitleaks** | The secret scanner that blocks commits/PRs containing API keys, tokens, or credentials. |
+| **ISO week** | Week numbering where week 1 contains the year's first Thursday — keeps `weekly/2026-W17.md` files sorting correctly across years. |
+| **Clone** | Downloading a copy of the repo to your computer (`git clone …`) so agents can work in it. |
+| **Inbox** | A local, gitignored scratch folder (`inbox/`) you create for raw drops — files you want the agent to file properly via the `update-wiki` skill. Never committed. |
+
+## Company terms
+
+<!-- Your domain vocabulary: product names, internal shorthand, market terms.
+One row each. Agents: when you meet an undefined company term, add it here
+(PR) rather than guessing. -->
+
+| Term | Meaning |
+|------|---------|