org-knowledge-layer 0.3.1__tar.gz → 0.4.1__tar.gz

org_knowledge_layer-0.4.1/.github/dependabot.yml

@@ -0,0 +1,32 @@
+# Dependabot.
+#
+# This exists because of the SHA pinning, not despite it. Pinning actions to a commit
+# closes the "a mutable tag moved under me" hole and opens a quieter one: the pin never
+# updates, so a security fix in an action never arrives. Pinning without an update path
+# is how a repo ends up on a two-year-old checkout action and calls it hardening.
+# Dependabot rewrites the SHA and the trailing `# v5` comment together.
+version: 2
+
+updates:
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+    labels: ["dependencies", "ci"]
+    commit-message:
+      prefix: "ci"
+
+  - package-ecosystem: pip
+    directory: "/"
+    schedule:
+      interval: weekly
+    labels: ["dependencies"]
+    commit-message:
+      prefix: "deps"
+    # The gating tools are pinned exactly on purpose (a range lets a new release
+    # retro-fail a branch that changed nothing). Dependabot is the intended way to move
+    # those pins: a PR that runs the full suite against the new version before it lands,
+    # rather than a range that upgrades silently mid-branch.
+    groups:
+      dev-tooling:
+        patterns: ["pytest", "ruff", "mypy"]

org_knowledge_layer-0.4.1/.github/workflows/ci.yml

@@ -0,0 +1,100 @@
+# Repo CI — lints, type-checks and tests okl itself. (okl-verify.yml is different: it
+# demonstrates the product's own drift/method gates, the workflow consumers copy.)
+#
+# Hardened per the org rule this repo's own store carries ("CI workflow baseline:
+# pipefail, no persisted credentials, least-privilege permissions, concurrency groups —
+# pin actions"). It satisfied none of the five until this commit, which is the rule's own
+# symptom: an enforcement surface nothing triggers runs never.
+name: ci
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+# Least privilege: this job reads code and reports status. It never pushes.
+permissions:
+  contents: read
+
+# One run per ref. A superseded push should stop burning minutes on a result nobody
+# will read.
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+defaults:
+  run:
+    # Without pipefail a run block continues past a failed segment of a pipeline, so a
+    # green step can hide a red command.
+    shell: bash -euo pipefail {0}
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      # Actions pinned to a commit SHA, not a tag: a tag is mutable, so `@v5` is an
+      # unpinned dependency with write access to the runner.
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09  # v5
+        with:
+          # The diagram gate reads committed history (git show HEAD:...), not the
+          # checkout tree, so it needs more than the default shallow fetch.
+          fetch-depth: 0
+          # This job never pushes; leaving the token in .git/config lets any later step
+          # (or a compromised dependency) use it.
+          persist-credentials: false
+
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1  # v6
+        with:
+          python-version: "3.12"
+
+      - name: Install (dev extras)
+        run: pip install -e ".[dev]"
+
+      - name: Lint — ruff (config in pyproject.toml)
+        run: ruff check .
+
+      - name: Types — mypy
+        run: mypy src/okl
+
+      - name: Tests (with the coverage ratchet)
+        run: pytest -q --cov=okl
+
+      - name: Diagram figures trace to committed receipts
+        run: ./ci/check-diagram-figures.sh
+
+      # The content audits okl ships to consumers, run against okl itself. They were
+      # shipped for weeks without this repo running any of them — the "enforcement
+      # surface nothing triggers" failure, one level up: a gate whose author has never
+      # run it on their own tree.
+      - name: Method gates (links, doc orphans, diagram pairs, tombstones, canon size)
+        run: bash gates/run-gates.sh
+
+      # Secret scan over the FULL history, not the working tree. okl writes a bearer
+      # token into .okl/config.json, and the .gitignore it now drops there is the only
+      # thing between that and a commit — this is the check for when that fails.
+      #
+      # The upstream gitleaks-action is deliberately not used: it requires a paid licence
+      # key for organization-owned repositories, so it would break for anyone who forks
+      # this into an org. The binary has no such condition, and pinning the release keeps
+      # a new detection rule from retro-failing a branch that changed nothing.
+      # The reviewer okl ships, run on okl. It was listed as a review surface with nothing
+      # triggering it — the "enforcement surface that only runs on-demand runs never"
+      # failure this repo's own store names. Off unless REVIEW_CMD is set, so it costs
+      # nothing until someone decides it should.
+      - name: Architecture review (off unless REVIEW_CMD is set)
+        if: github.event_name == 'pull_request'
+        env:
+          REVIEW_CMD: ${{ vars.REVIEW_CMD }}
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          REVIEW_BASE_REF: origin/${{ github.base_ref }}
+        run: bash ci/review-agent.sh
+
+      - name: Secret scan — gitleaks
+        env:
+          GITLEAKS_VERSION: "8.30.1"
+        run: |
+          curl -sSfL -o /tmp/gitleaks.tar.gz \
+            "https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/gitleaks_${GITLEAKS_VERSION}_linux_x64.tar.gz"
+          tar -xzf /tmp/gitleaks.tar.gz -C /tmp gitleaks
+          /tmp/gitleaks git . --no-banner --redact --exit-code 1

{org_knowledge_layer-0.3.1/src/okl/scaffold/ci → org_knowledge_layer-0.4.1/.github/workflows}/okl-verify.yml

@@ -16,16 +16,45 @@ on:
   push:
     branches: [main]
 
+# Least privilege: this workflow reads code and reports a status. It never writes.
+permissions:
+  contents: read
+
+concurrency:
+  group: okl-verify-${{ github.ref }}
+  cancel-in-progress: true
+
+defaults:
+  run:
+    # Without pipefail a run block continues past a failed segment of a pipeline, so a
+    # green step can hide a red command.
+    shell: bash -euo pipefail {0}
+
 jobs:
   okl-verify:
     runs-on: ubuntu-latest
+    env:
+      # Set at job level so every okl command below resolves the shared layer from the
+      # environment. This replaces an `okl connect --token` step, which wrote the bearer
+      # token into .okl/config.json on the runner — needless, since the client reads both
+      # variables directly, and one more place for a credential to end up.
+      # Unset secrets leave these empty, and okl falls back to the repo-local store.
+      OKL_SERVICE_URL: ${{ secrets.OKL_SERVICE_URL }}
+      OKL_TOKEN: ${{ secrets.OKL_TOKEN }}
     steps:
-      - uses: actions/checkout@v4
+      # Actions are pinned to a commit SHA: a tag is mutable, so `@v5` is an unpinned
+      # dependency with access to your runner. If you copy this file into your own repo,
+      # add a .github/dependabot.yml with the `github-actions` ecosystem so these pins get
+      # security updates — a pin with no update path goes stale and that is its own risk.
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09  # v5
         with:
-          fetch-depth: 0   # drift needs history: it compares file mtimes/commits vs verified_at
-      - uses: actions/setup-python@v5
+          fetch-depth: 0   # drift needs history: it compares governed-file commits vs verified_at
+          persist-credentials: false   # this job never pushes
+
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1  # v6
         with:
           python-version: "3.13"
+
       - name: Install okl
         # Detect by the package source, not the distribution name: the name changed once
         # (PyPI rejects "okl" as confusable) and a name-based check silently broke with it.
@@ -36,13 +65,10 @@ jobs:
             pip install org-knowledge-layer
           fi
 
-      - name: Connect to the shared layer (optional — skipped when secrets are unset)
-        env:
-          OKL_SERVICE_URL: ${{ secrets.OKL_SERVICE_URL }}
-          OKL_TOKEN: ${{ secrets.OKL_TOKEN }}
+      - name: Report which store the gate will run against
         run: |
           if [ -n "${OKL_SERVICE_URL:-}" ]; then
-            okl connect "$OKL_SERVICE_URL" --token "$OKL_TOKEN"
+            echo "verifying against the shared layer at $OKL_SERVICE_URL"
           else
             echo "no OKL_SERVICE_URL secret — verifying against the repo-local store"
           fi

org_knowledge_layer-0.4.1/.github/workflows/publish.yml

@@ -0,0 +1,90 @@
+# Release to PyPI on a version tag, using Trusted Publishing.
+#
+# There is no API token anywhere in this workflow, and none stored in the repository.
+# PyPI accepts the upload because GitHub vouches for it: the publish job mints a
+# short-lived OIDC token that names this repository, this workflow file and this
+# environment, and PyPI checks that against the trusted publisher it was told to expect.
+# A leaked repository secret cannot publish okl because there is no such secret.
+#
+# ONE-TIME SETUP ON PYPI (this workflow does nothing until it is done):
+#   pypi.org → the org-knowledge-layer project → Publishing → Add a pending publisher
+#     Owner:            emeraldleaf
+#     Repository:       okl
+#     Workflow name:    publish.yml
+#     Environment name: pypi
+# Then create the `pypi` environment under repo Settings → Environments. Adding a
+# required reviewer there makes every release a deliberate, approved act.
+name: publish
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09  # v5
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1  # v6
+        with:
+          python-version: "3.12"
+
+      # The tag is the release's claim about what version this is; pyproject.toml is the
+      # version that actually gets uploaded. When they disagree, PyPI takes pyproject's
+      # answer and the tag becomes a lie that is permanent — you cannot reuse a version
+      # number on PyPI, so the mistake is not fixable, only worked around.
+      - name: Tag must match the version in pyproject.toml
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          pkg="$(python -c "import tomllib,pathlib; print(tomllib.loads(pathlib.Path('pyproject.toml').read_text())['project']['version'])")"
+          echo "tag=$tag  pyproject=$pkg"
+          if [ "$tag" != "$pkg" ]; then
+            echo "::error::tag v$tag does not match pyproject version $pkg"
+            exit 1
+          fi
+
+      - name: Build
+        run: |
+          python -m pip install --upgrade build twine
+          python -m build
+          # `twine check` catches a malformed long_description, which PyPI rejects only
+          # after the upload has otherwise succeeded.
+          python -m twine check dist/*
+
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02  # v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    # A named environment is what the PyPI trusted publisher is bound to, and it is where
+    # a required-reviewer rule can gate the release.
+    environment:
+      name: pypi
+      url: https://pypi.org/project/org-knowledge-layer/
+    permissions:
+      id-token: write      # mint the OIDC token PyPI verifies
+      attestations: write  # sign the artifacts
+      contents: read
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093  # v4
+        with:
+          name: dist
+          path: dist/
+
+      # Provenance: a signed statement that these exact files were built by this workflow
+      # from this commit. It is what lets someone verify the wheel on PyPI came from the
+      # source they are reading, rather than trusting that it did.
+      - uses: actions/attest-build-provenance@e8998f949152b193b063cb0ec769d69d929409be  # v2
+        with:
+          subject-path: "dist/*"
+
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33  # release/v1

{org_knowledge_layer-0.3.1 → org_knowledge_layer-0.4.1}/AGENTS.md

@@ -31,8 +31,9 @@ okl drift                          # rules whose governed source changed after v
 ## Rules that are enforced (and why)
 
 - **Mirror files are byte-identical, test-enforced**: `ci/okl-verify.yml` ==
-  `.github/workflows/okl-verify.yml` == `src/okl/scaffold/ci/okl-verify.yml`, and
-  `hooks/*.sh` == `src/okl/scaffold/hooks/*.sh`. The scaffold copies are what consumers
+  `.github/workflows/okl-verify.yml` == `src/okl/scaffold/ci/okl-verify.yml`,
+  `hooks/*.sh` == `src/okl/scaffold/hooks/*.sh`, and
+  `gates/*.sh` == `src/okl/scaffold/gates/*.sh`. The scaffold copies are what consumers
   receive; the repo copies are the dogfood. Edit ONE, copy to the others in the same
   change — `tests/test_scaffold.py::test_mirror_files_identical` fails otherwise.
 - **ruff `E702` is ignored deliberately** (semicolon one-liners): the tests use a

org_knowledge_layer-0.4.1/CHANGELOG.md

@@ -0,0 +1,145 @@
+# Changelog
+
+## 0.4.1
+
+### Security — affects the CI workflow already in your repo
+
+- **The shipped CI verifier no longer writes your bearer token to disk.** It ran
+  `okl connect --token`, which persisted `OKL_TOKEN` into `.okl/config.json` on the runner
+  for no reason: the client reads `OKL_SERVICE_URL` and `OKL_TOKEN` from the environment
+  directly, so setting them at job level does the same work with the credential never
+  touching the filesystem. Re-run `okl init` (or `okl scaffold`) to pick up the new file.
+- **Both shipped workflows are hardened.** `okl-verify.yml` and `method-gates.yml` now
+  declare least-privilege `permissions`, a concurrency group, `pipefail`, and
+  `persist-credentials: false`, and pin their actions to commit SHAs rather than mutable
+  tags. They satisfied none of that before.
+- `.github/dependabot.yml` ships with the kit, because pinning to a SHA without an update
+  path is how a repo ends up on a two-year-old action and calls it hardening.
+
+### Added
+
+- **Opt-in architecture review in CI.** `ci/review-agent.sh` runs the reviewer over a PR
+  diff and fails on must-fix findings. **Off unless you set the `REVIEW_CMD` repository
+  variable** to a CLI that reads a prompt on stdin — `claude -p` (authenticates with an
+  existing Claude Code login, no separate API key), `ollama run <model>` (local, free), or
+  any other. Unset, it prints one line and passes. It is the only gate in the kit that
+  calls a model, which is why it is the only one that is opt-in. Documented in the README
+  and the kit manifest.
+
+
+## 0.4.0
+
+### Behaviour changes worth reading before upgrading
+
+- **Stack tags now filter exclusively.** A record naming a stack (`dotnet`, `react`,
+  `geospatial`, `python`, `python-rag`) is only shown to a repo that declared that stack
+  in its `interests`. Previously any shared tag let it through, so a rule tagged
+  `dotnet,method` reached every repo interested in `method` — a subject 75 records carry.
+  **If you declare `interests`, expect fewer records after upgrading.** That is the point,
+  but it is a change in what your briefings contain. Repos that declare no interests are
+  unaffected, and untagged records still always pass.
+- **`symptom` and `fix` are now searchable.** They were not, which meant a record written
+  the way the docs tell you to write it — short title, the distinguishing words in the
+  symptom — could not be retrieved at all. Existing stores rebuild their index on first
+  open; you do not need to re-record anything.
+
+### Added
+
+- **`okl dedup`** reports near-duplicate records for review. Lexical and explainable:
+  per-field weighted Jaccard over title, symptom and fix, IDF-weighted from your own
+  corpus. It never merges or drops anything — the measured score bands for true
+  paraphrases and for distinct-but-related records overlap, so the call is a person's.
+  The same check runs as an advisory when importing an agent-proposed pack.
+- **`/seed-from-docs`** mines the specs, ADRs and rules files you already wrote into typed
+  records. Built around one distinction: a record is a standing instruction that outlives
+  the work item it came from, so "deep offsets use keyset pagination" belongs and "add
+  pagination to /orders this sprint" does not.
+- A pack declaring `_proposed_by` is refused unless every node carries a `found_by`
+  citation, so the rule the seeding commands state is enforced at import rather than
+  remembered by a reviewer.
+
+### Fixed
+
+- `Client._remote_url` validates the URL scheme once. A `service_url` from config could
+  name `file://`, turning a remote read into a local file read.
+- `OKLUnreachable` is now `OKLUnreachableError`, with the old name kept as an alias so
+  existing `except` clauses still work.
+- Drift timestamps are timezone-aware; `utcfromtimestamp` is deprecated from Python 3.12
+  and returned a naive datetime that read as local time when compared across machines.
+
+### Internal
+
+- `_Backend` is a `typing.Protocol` whose docstring states the behavioural contract, with
+  one conformance test both backends run — the defect it guards (Postgres satisfying every
+  signature while running an unranked match) was invisible to signatures alone.
+- mypy, and ruff widened from 6 rule families to 15 including security and complexity,
+  both wired into CI alongside a secret scan, the method gates and a coverage floor.
+
+
+## 0.3.1
+
+### Security
+
+- **Setting `OKL_TOKEN` now also removes `/openapi.json`, `/docs` and `/redoc`.** They
+  were left serving 200 to anonymous callers by the 0.3.0 work that closed every data
+  route, because FastAPI mounts them itself — they are not handlers, so the per-handler
+  auth sweep could not reach them. They leak no records, but they publish the endpoint
+  list, every schema, and which routes want a credential. With no token set the
+  interactive docs remain available, since that case is a developer's laptop.
+
+## 0.3.0
+
+Everything here came from running three things that had been written but never
+executed: the MCP server, the Postgres backend, and a deployment.
+
+### Security
+
+- **The service token now covers reads.** Previously `OKL_TOKEN` gated writes only, so
+  an unauthenticated `GET /nodes` returned the entire store — every recorded defect,
+  retired identifier and architecture decision. Every route now requires the token when
+  it is set, except `/health`, which is left open for schedulers and returns no record
+  content.
+- **`okl connect --token` no longer commits your secret.** The token is stored in
+  cleartext in `.okl/config.json`, and a comment claimed the directory was gitignored
+  while nothing wrote a `.gitignore`. `okl init` and `okl connect` now write
+  `.okl/.gitignore`.
+- **A rejected check no longer reports success.** A 401 surfaced as `ValueError` rather
+  than `OKLUnreachable`, so an unauthorized `okl check` exited 0 with a traceback — which
+  a pre-task hook reads as "no rules apply". It now fails closed with exit 2, as does
+  every other command, via a backstop in `main()`.
+
+**Breaking:** if you run a service with `OKL_TOKEN` set, clients must upgrade too.
+Clients older than 0.3.0 send no credential on `GET` requests and will get 401s from
+`okl drift` and the recurrence metric. Upgrade the service and its clients together, or
+unset `OKL_TOKEN` during the rollover.
+
+### Fixed
+
+- `uvicorn okl.service:app` served a module-level `None`: the process started, bound the
+  port, passed a port-liveness check and returned 500 to every request. The app is now
+  built lazily in a module `__getattr__`, so the standard ASGI entrypoint works while
+  importing the module still does not touch the database.
+- The MCP server could not start under `mcp` 2.x, which renamed `FastMCP` to
+  `MCPServer` — and the error handler told you to install the extra you had just
+  installed. Both names are tried, and the real import error is reported.
+- Every MCP `okl_record` call with `scope="repo"` failed. The repo default used
+  `setdefault`, which cannot replace an explicit `None`, and the MCP tools pass every
+  field explicitly.
+- MCP validation errors raised as an opaque "Error executing tool". They now return the
+  complaint, so an agent that invents a tag is told the vocabulary.
+
+### Added
+
+- `docs/DEPLOY.md`: the shared-service deployment path, including a throwaway Postgres
+  for trying it locally and what each failure mode looks like. Every command in it was
+  run against a real Postgres and a real service.
+- Tests covering the live MCP server, the ASGI entrypoint, service auth on reads, the
+  fail-closed 401, and the config `.gitignore`.
+- The Postgres/SQLite parity test now runs in a scratch schema it creates and drops. The
+  first version opened with `DELETE FROM node` against whatever `OKL_TEST_POSTGRES_URL`
+  pointed at, which would have destroyed the store of anyone who set it to their real
+  service.
+
+## 0.2.0 and earlier
+
+See the git history.

{org_knowledge_layer-0.3.1 → org_knowledge_layer-0.4.1}/CLAUDE.md

@@ -31,8 +31,9 @@ okl drift                          # rules whose governed source changed after v
 ## Rules that are enforced (and why)
 
 - **Mirror files are byte-identical, test-enforced**: `ci/okl-verify.yml` ==
-  `.github/workflows/okl-verify.yml` == `src/okl/scaffold/ci/okl-verify.yml`, and
-  `hooks/*.sh` == `src/okl/scaffold/hooks/*.sh`. The scaffold copies are what consumers
+  `.github/workflows/okl-verify.yml` == `src/okl/scaffold/ci/okl-verify.yml`,
+  `hooks/*.sh` == `src/okl/scaffold/hooks/*.sh`, and
+  `gates/*.sh` == `src/okl/scaffold/gates/*.sh`. The scaffold copies are what consumers
   receive; the repo copies are the dogfood. Edit ONE, copy to the others in the same
   change — `tests/test_scaffold.py::test_mirror_files_identical` fails otherwise.
 - **ruff `E702` is ignored deliberately** (semicolon one-liners): the tests use a

org_knowledge_layer-0.3.1/README.md → org_knowledge_layer-0.4.1/PKG-INFO

@@ -1,3 +1,37 @@
+Metadata-Version: 2.5
+Name: org-knowledge-layer
+Version: 0.4.1
+Summary: Org Knowledge Layer — an installable sixth surface that carries encoded engineering lessons across repos.
+Author: Joshua Dell
+License: MIT
+License-File: LICENSE
+Keywords: agentic-coding,ai-engineering,encoding-loop,knowledge-layer,mcp
+Requires-Python: >=3.10
+Provides-Extra: all
+Requires-Dist: fastapi>=0.110; extra == 'all'
+Requires-Dist: mcp>=1.2; extra == 'all'
+Requires-Dist: psycopg[binary]>=3.1; extra == 'all'
+Requires-Dist: pydantic>=2; extra == 'all'
+Requires-Dist: uvicorn>=0.29; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: fastapi>=0.110; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: mypy==2.3.1; extra == 'dev'
+Requires-Dist: pydantic>=2; extra == 'dev'
+Requires-Dist: pytest-cov==7.1.0; extra == 'dev'
+Requires-Dist: pytest==8.4.2; extra == 'dev'
+Requires-Dist: ruff==0.16.5; extra == 'dev'
+Requires-Dist: uvicorn>=0.29; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == 'mcp'
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]>=3.1; extra == 'postgres'
+Provides-Extra: service
+Requires-Dist: fastapi>=0.110; extra == 'service'
+Requires-Dist: pydantic>=2; extra == 'service'
+Requires-Dist: uvicorn>=0.29; extra == 'service'
+Description-Content-Type: text/markdown
+
 # okl — a shared knowledge layer for AI-assisted engineering
 
 > A small database of the specific lessons a codebase has learned — the bugs it
@@ -46,6 +80,17 @@ Two things ship in the package. They are not coequal:
   retrieved into an agent's context before a task, and go stale loudly when the code
   they describe moves on. Everything measured in [evals/REPORT.md](evals/REPORT.md)
   measures this.
+
+  It is worth being precise about what that store fills up with, because "lessons a
+  codebase has learned" invites the picture of a bug database. In the 161-record corpus
+  in [seed/](seed/) it is mostly not that: **90 Rules, 20 Decisions and 7 Gates against
+  34 Defects** — conventions the code follows and trade-offs already settled, not a
+  ledger of things that broke. Count it yourself:
+
+  ```bash
+  python3 -c "import json,glob,collections; c=collections.Counter(
+    n['type'] for f in glob.glob('seed/*.json') for n in json.load(open(f))['nodes']); print(c)"
+  ```
 - **`okl scaffold`** is a starter kit for the in-repo discipline the store assumes: a
   lean canon file, mechanical gates, registries, a review agent, and an eval harness.
   It is useful on its own and it has never been measured. Use it to get a new repo to
@@ -163,6 +208,8 @@ with receipts, not a benchmark.
 
 ## How it works
 
+<img src="docs/okl-how-it-works.svg" alt="One repo records a lesson; every other repo is briefed on it before its next task. The store is typed, scoped and tagged; every verification stamp carries the check that earned it." width="100%">
+
 ### The mental model
 
 `okl` stores small, typed **notes** and the **links** between them.
@@ -258,6 +305,85 @@ pip install "org-knowledge-layer[mcp]"        # MCP server for Claude Code / Cur
 pip install "org-knowledge-layer[all]"
 ```
 
+## What it costs, and how to turn it down
+
+Installing okl is not free. It is worth knowing exactly what you are signing up for
+before you wire it into every prompt, and every number below was measured on this repo's
+own 199-record store rather than estimated.
+
+**Per prompt, once the hook is installed:**
+
+| | |
+|---|---|
+| Latency | **~0.11s** — one local SQLite query, no network in local mode |
+| Context | **~2,300 tokens** at the default `--limit 12`, down to **~250** at `--format actions --limit 3` |
+
+**Per session:** the Stop hook interrupts once at the end to ask what was learned. It
+blocks the first stop only, and answering it is the whole write side of the loop.
+
+**In your repo:** `okl init` writes `.okl/` (config, the local database, a `.gitignore`
+covering both) and, if `.claude/` exists, two hook scripts plus their registration. It
+also installs `.github/workflows/okl-verify.yml`, which runs the drift gate on every PR.
+`okl scaffold` is separate and optional — nothing installs it unless you ask.
+
+### The knobs, cheapest first
+
+```bash
+okl check --task "..." --format actions   # imperatives only, ~60% smaller
+okl check --task "..." --limit 3          # fewer records; the briefing says how many it trimmed
+okl init --interests "python,security"    # drop records tagged for stacks you do not use
+```
+
+- **`--format actions`** is the single biggest saving and loses the least: you keep every
+  "when you see X → do Y" and drop the explanatory prose.
+- **`--limit N`** caps how many records are drawn on. The briefing always reports what it
+  trimmed, so a short briefing can never quietly hide a miss.
+- **`interests`** is the one to reach for on a mature shared store. Stack tags filter
+  exclusively — declaring `python` means records tagged `dotnet` stay out even when they
+  share a subject tag with something you asked for.
+- **Scope records `repo:` rather than `org`** when a lesson is local. Org scope is a claim
+  that every project in the organization should see it, and it costs every project's
+  budget to be wrong about that.
+
+### Turning parts off
+
+The hooks are registered in `.claude/settings.json`; delete the entry to stop one firing.
+The pre-task hook is the read side and the Stop hook is the write side, and they are
+independent — running the read without the write is a reasonable way to start.
+
+Nothing is load-bearing on the hooks: `okl check` and `okl record` work from the terminal,
+from CI, and through the MCP server whether or not any hook is installed.
+
+To remove okl from a repo entirely, delete `.okl/`, the two hook scripts and their entries
+in `.claude/settings.json`, and `.github/workflows/okl-verify.yml`. Nothing else was
+written, and nothing outside that repo was touched.
+
+### Architecture review in CI (off by default)
+
+The kit ships a reviewer that reads a PR diff against your encoded rules and fails the
+build on a must-fix finding. It is **off unless you ask for it**, and it is not tied to any
+vendor. Set the `REVIEW_CMD` repository variable to any CLI that reads a prompt on stdin:
+
+```bash
+gh variable set REVIEW_CMD --body "claude -p --model sonnet"   # your existing Claude Code login
+gh variable set REVIEW_CMD --body "ollama run qwen2.5-coder"   # local model, no API cost
+gh variable set REVIEW_CMD --body "llm -m gpt-4o"              # any other CLI
+```
+
+Two things worth knowing:
+
+- **`claude -p` needs no separate API key.** It authenticates with the Claude Code login you
+  already have, so if you use Claude Code there is nothing else to configure and no second
+  bill. Verified headless with `ANTHROPIC_API_KEY` unset.
+- **Locally you do not need this at all.** The reviewer is a subagent
+  (`.claude/agents/architecture-reviewer.md`); ask your agent to run it on your changes and
+  it costs nothing beyond the session you are already in. The CI job exists for the case
+  where no human and no agent is in the loop — a PR nobody reviewed.
+
+Unset, the step prints one line saying it is off and exits 0. Every other gate in the kit is
+deterministic and free; this is the only one that calls a model, which is why it is the only
+one that is opt-in.
+
 ## Wire a repo
 
 ```bash
@@ -371,7 +497,7 @@ okl metric           # recurrence-after-arming: defect classes that came back in
 
 ## Subagents and small context budgets
 
-A full briefing costs roughly **4,400 tokens** — fine for a main session with a large
+A full briefing costs roughly **2,300 tokens** — fine for a main session with a large
 window, punishing for a subagent working in a few thousand. That asymmetry matters
 because subagents are exactly where org rules get lost: a focused worker handling one
 subtask has the least context and the most need for "here is the mistake this codebase