org-knowledge-layer 0.1.3__tar.gz → 0.3.0__tar.gz

{org_knowledge_layer-0.1.3 → org_knowledge_layer-0.3.0}/.claude/settings.local.json

@@ -97,13 +97,72 @@
       "Bash(./v12test/bin/pip install *)",
       "Bash(./v12test/bin/okl --help)",
       "Bash(./v12test/bin/python -c ' *)",
-      "Bash(ruff check *)"
+      "Bash(ruff check *)",
+      "Bash(curl -s \"https://pypi.org/pypi/org-knowledge-layer/0.1.3/json\")",
+      "Bash(/tmp/v13/bin/pip show *)",
+      "Bash(xargs -I{} gh run view {} --log-failed)",
+      "Bash(grep -vE \"^$\")",
+      "Bash(git -c core.hooksPath=/dev/null commit -qm 'Fix the CI break the PyPI rename caused: detect by source, not by name *)",
+      "Bash(git -c core.hooksPath=/dev/null commit -qm 'README: say what okl is, and exactly what it keeps from drifting *)",
+      "Bash(sed 's|cd \"$\\(dirname \"$0\"\\)/\\\\.\\\\.\"|cd \"$\\(pwd\\)\"|' src/okl/scaffold/gates/check-links.sh)",
+      "Bash(bash /tmp/links.sh)",
+      "Bash(sed 's|cd \"$\\(dirname \"$0\"\\)/\\\\.\\\\.\"|cd \"$\\(pwd\\)\"|' src/okl/scaffold/gates/check-diagram-pairs.sh)",
+      "Bash(bash /tmp/dia.sh)",
+      "Bash(git -C /Users/joshuadell/NovaCraft log --oneline --diff-filter=A -- \".claude/skills/excalidraw-diagram/SKILL.md\")",
+      "Bash(git -C /Users/joshuadell/NovaCraft log --format=\"%h %ad %s\" --date=short --diff-filter=A -- \".claude/skills/excalidraw-diagram/\")",
+      "Bash(git -C /Users/joshuadell/NovaCraft log --oneline -- \".claude/skills/excalidraw-diagram/\")",
+      "Bash(git -c core.hooksPath=/dev/null commit -qm 'Be accurate about which agents get enforcement, and about what init writes *)",
+      "Bash(tee /tmp/briefing.txt)",
+      "Bash(awk '{printf \"payload: %s bytes, ~%d tokens\\\\n\",$1,$1/4}')",
+      "Bash(/tmp/v13/bin/okl check *)",
+      "Bash(/tmp/v13/bin/okl seed *)",
+      "Bash(python3 -m okl seed)",
+      "Bash(/Users/joshuadell/Dev/okl/.venv/bin/okl seed *)",
+      "Bash(python3 -m okl init --repo myproject --interests \"security,python-rag\")",
+      "Bash(echo \"=== exit=$? \\(nothing imported\\) ===\")",
+      "Bash(python3 -m okl seed /Users/joshuadell/Dev/okl/seed/rag-defects.json)",
+      "Bash(python3 -m okl seed /Users/joshuadell/Dev/okl/seed/dotnet-defects.json)",
+      "Bash(sqlite3 .okl/okl.db \"select count\\(*\\) from node;\")",
+      "Bash(python3 -m okl check --task \"add an endpoint that returns an order for the logged-in user\")",
+      "Bash(awk '{printf \"briefing now: %s bytes \\(~%d tokens\\), was ~4381\\\\n\",$1,$1/4}')",
+      "Bash(python3 -m okl bootstrap --repo myproject)",
+      "Bash(seed)",
+      "Bash(check)",
+      "Bash(okl bootstrap *)",
+      "Bash(git -c core.hooksPath=/dev/null commit -qm 'First-run experience: seeding is a choice, briefings are capped, empty states are honest *)",
+      "Bash(git -c core.hooksPath=/dev/null commit -q --amend -F /tmp/msg.txt)",
+      "Bash(git -c core.hooksPath=/dev/null commit -qm 'v0.2.0 *)",
+      "Bash(command -v postgres pg_ctl initdb)",
+      "Read(//opt/homebrew/opt/**)",
+      "Bash(python3 -c \"import mcp; print\\(mcp.__version__ if hasattr\\(mcp,'__version__'\\) else 'installed'\\)\")",
+      "Bash(python3 -m pip install -q \"psycopg[binary]>=3.1\")",
+      "Bash(python3 -m pip install -q \"mcp>=1.2\")",
+      "Bash(python3 -c \"import mcp; print\\('mcp installed'\\)\")",
+      "Bash(python3 -c \"import mcp, importlib.metadata as md; print\\('installed mcp version:', md.version\\('mcp'\\)\\)\")",
+      "Bash(python3 -c \"from mcp.server.mcpserver import MCPServer; print\\('MCPServer exists'\\); import inspect; print\\('has .tool\\(\\):', hasattr\\(MCPServer, 'tool'\\)\\); print\\('has .list_tools\\(\\):', hasattr\\(MCPServer,'list_tools'\\)\\); print\\('has .run\\(\\):', hasattr\\(MCPServer,'run'\\)\\)\")",
+      "Bash(python3 -m pytest -q -k \"mcp_server_builds or postgres_matches\" -v)",
+      "Bash(OKL_TEST_POSTGRES_URL=\"postgresql://joshuadell@/postgres?host=/tmp/oklpg&port=55432\" python3 -m pytest -q -k \"postgres_matches\" -v)",
+      "Bash(python3 -c \"import importlib.metadata as m; print\\(m.version\\('mcp'\\)\\)\")",
+      "Bash(OKL_TEST_POSTGRES_URL=\"postgresql://joshuadell@/postgres?host=/tmp/oklpg&port=55432\" python3 -m pytest -k \"postgres_matches\")",
+      "Bash(export OKL_TEST_POSTGRES_URL=\"postgresql://okl@/okltest?host=/tmp/oklpg&port=55432\")",
+      "Bash(python3 -m pytest -q -k \"postgres_matches\")",
+      "Bash(export OKL_DATABASE_URL=\"postgresql://okl@/okltest?host=/tmp/oklpg&port=55432\")",
+      "Bash(export OKL_TOKEN=\"deploy-test-secret\")",
+      "Bash(python3 -m uvicorn --factory okl.service:create_app --host 127.0.0.1 --port 8791)",
+      "Bash(echo \"started pid $!\")",
+      "Bash(curl -s http://127.0.0.1:8791/health)",
+      "Bash(OKL_TEST_POSTGRES_URL=\"postgresql://okl@/okltest?host=/tmp/oklpg&port=55432\" python3 -m pytest -q)",
+      "Bash(pkill -f uvicorn)",
+      "Bash(pg_ctl -D /tmp/oklpg/data stop -m immediate)",
+      "Bash(tmutil listlocalsnapshots *)",
+      "Bash(python3 -c \"import json,sys; print\\(', '.join\\(sorted\\(json.load\\(sys.stdin\\)['releases']\\)\\)\\)\")"
     ],
     "additionalDirectories": [
       "/Users/joshuadell/Dev/okl/e2e/scratch-briefed/.okl",
       "/Users/joshuadell/Dev/emeraldleaf-dev/src/pages",
       "/Users/joshuadell/Dev/emeraldleaf-dev/src/assets",
-      "/Users/joshuadell/Dev/emeraldleaf-dev/src"
+      "/Users/joshuadell/Dev/emeraldleaf-dev/src",
+      "/Users/joshuadell/NovaCraft/.claude/skills/excalidraw-diagram"
     ]
   }
 }

{org_knowledge_layer-0.1.3/src/okl/scaffold/ci → org_knowledge_layer-0.3.0/.github/workflows}/okl-verify.yml

@@ -27,13 +27,13 @@ jobs:
         with:
           python-version: "3.13"
       - name: Install okl
-        # Consumer repos install the released package; in okl's own repo this
-        # workflow dogfoods the working tree (pip install okl would 404 — not on PyPI yet).
+        # 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.
         run: |
-          if grep -q '^name = "okl"' pyproject.toml 2>/dev/null; then
+          if [ -f src/okl/cli.py ]; then
             pip install -e .
           else
-            pip install okl
+            pip install org-knowledge-layer
           fi
 
       - name: Connect to the shared layer (optional — skipped when secrets are unset)

org_knowledge_layer-0.3.0/CHANGELOG.md

@@ -0,0 +1,58 @@
+# Changelog
+
+## 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.1.3 → org_knowledge_layer-0.3.0}/CONTRIBUTING.md

@@ -49,6 +49,17 @@ it is the actual contract. The parts that will fail your build if you miss them:
   cutoff that is still unfinished.
 - **Portability fixes.** Hooks, path resolution, and CI have been exercised on macOS and
   GitHub Actions and nowhere else.
+- **Hook wiring for another agent.** `okl init` auto-registers hooks for Claude Code
+  only, so everywhere else the pre-task read is discretionary rather than enforced. The
+  scripts in `src/okl/scaffold/hooks/` are plain bash reading JSON on stdin and writing
+  the briefing to stdout; nothing in them is Claude-specific. What is missing is the
+  per-agent registration, plus confirming the agent fires an event before the model reads
+  the prompt (Codex CLI documents `userpromptsubmit`; OpenCode's plugin API appears to
+  cover tool events but not pre-prompt, so there it may only ever be a tool call). A PR adding `okl init --agent <name>` for the tool you actually use
+  daily would be the single most valuable contribution here. Bring evidence it fires: a
+  behavioral check against a bare control repo, not just a log line, because a hook that
+  fires is not a hook that is heard.
+
 - **A live-Postgres test.** The ranked search path for Postgres is currently asserted at
   the SQL-shape level against a fake connection; it has never run against a real server.
 

{org_knowledge_layer-0.1.3 → org_knowledge_layer-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: org-knowledge-layer
-Version: 0.1.3
+Version: 0.3.0
 Summary: Org Knowledge Layer — an installable sixth surface that carries encoded engineering lessons across repos.
 Author: Joshua Dell
 License: MIT
@@ -67,6 +67,58 @@ stdlib-only with zero required dependencies.
 
 ---
 
+## What okl is
+
+**A store of your engineering rules, and the machinery that keeps them true.**
+
+Two things ship in the package. They are not coequal:
+
+- **The knowledge layer** is the product. Typed records (rules, architecture decisions,
+  known defects, gates, tombstones, retractions) that live outside any one repo, get
+  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.
+- **`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
+  the state where a shared store has something to attach to.
+
+| Piece | What it is | Where it lives |
+|---|---|---|
+| **client** (`okl` CLI + agent tools) | `check` / `record` / `verify` / `drift` / `search` / `seed` | installed per-repo (this package) |
+| **shared layer** (`okl serve`) | one small service owning the database, so many repos share one store | one place you run it |
+| **scaffold** (`okl scaffold`) | the in-repo starter files: canon, gates, registries, evals | stamped into each repo, optional |
+
+## What it keeps from drifting, and how
+
+Knowledge rots in a specific way: the code changes and everything written *about* the
+code silently stops being true. Five mechanisms catch five different versions of that,
+and it is worth knowing which one catches what, because they do not overlap.
+
+| Drift | Caught by | How it works | Fires when |
+|---|---|---|---|
+| **A rule vs. the code it governs** | `okl drift --gate` | a record declares the path globs it governs; git is asked for the last commit touching them | that commit is newer than the record's last verification |
+| **A retired identifier reappearing in prose** | `check-tombstones.sh` | greps tracked source, docs, comments and config for every tombstoned name | any non-allowlisted hit |
+| **A withdrawn claim being restated** | `check-retractions.sh` | greps tracked docs for the exact quoted claim from the retraction registry | the quote appears outside the registry |
+| **A doc nobody links to** | `check-doc-orphans.sh` | reachability check from hub files through `docs/` | a doc is unreachable, so it drifts unread |
+| **A link pointing at a file that moved** | `check-links.sh` | resolves every local markdown link against `git ls-files` | the target does not exist |
+| **A diagram source with no rendered image** | `check-diagram-pairs.sh` | pairs each editable source with its export; format-agnostic via `OKL_DIAGRAM_SRC_EXT`/`OUT_EXT` | reviewers would see nothing. A hand-authored image with no source is noted, never failed, and a repo with no diagram sources is a clean no-op |
+| **Verification going quietly stale** | TTL + `verified_by` | records carry when they were last verified and by which observed check | past its TTL, a record is shown demoted rather than deleted |
+
+Two honest limits on that table:
+
+- **Diagram *content* is still a human job.** `check-diagram-pairs.sh` proves the rendered
+  image exists; nothing proves it matches the source it was exported from, or that either
+  matches the code. For that, name the diagram in a record's `--files` alongside the code
+  it depicts, so changing the code turns the drift gate red until someone re-verifies the
+  picture. This repo does exactly that with its own architecture diagram and README.
+- **Comments are covered only by the identifier and claim gates.** A stale comment that
+  names no tombstoned identifier and restates no retracted claim will not be caught.
+- **`okl drift` only watches what a record claims.** A file no record governs is not
+  watched by anything. Coverage is a curation decision, and the gap is invisible until
+  something breaks — which is why the mechanical gates above scan *everything tracked*
+  rather than only what is enrolled.
+
 ## Where this sits (2026): a crowded space, entered anyway
 
 **This is not a novel idea, and you should know that before reading further.** Agent
@@ -284,6 +336,18 @@ reading the AGENTS.md convention gets the same rules Claude Code does (byte-iden
 test-enforced). The hooks themselves are Claude Code-specific; other agents get the
 canon via AGENTS.md and the store via the MCP server (`okl mcp`).
 
+That split matters: on Claude Code the pre-task read is *enforced* (fail-closed hook);
+everywhere else it is *available* (a tool call or a shell command), which is
+discretionary — the thing enforcement exists to avoid. The hook scripts themselves are
+plain bash reading JSON on stdin, so nothing in them is Claude-specific; what is missing
+for other agents is the config that registers them, and whether the agent fires an event
+early enough to matter. Codex CLI documents a `userpromptsubmit` hook, which is the right
+shape; Copilot, Gemini CLI and Cursor have hook systems worth checking against your
+version; OpenCode's plugin API captures tool events but, as of this writing, no
+pre-prompt event — so there the read stays a tool call rather than a gate. Verify against
+your agent's current docs before trusting any of that. Wiring one up is a well-shaped
+contribution — see [CONTRIBUTING.md](CONTRIBUTING.md).
+
 Hooks run in whatever environment the agent harness spawns — often without your venv or
 pipx bin dir on PATH — so both hooks resolve the `okl` binary in layers: the `OKL_BIN`
 env var, then the `okl_bin` path `init` pins into `.okl/config.json` (machine-local),
@@ -298,6 +362,7 @@ mode, good for trying it before you deploy anything.
 ```bash
 # 1. READ the relevant lessons before starting a task (the load-bearing move)
 okl check --task "add an endpoint that returns an order for the logged-in user"
+#   add --format actions --limit 3 for a ~240-token version (subagents, CI)
 
 # 2. RECORD a lesson after you learn it, with an actionable symptom/cause/fix
 okl record --type Defect --scope org --tags "security" \
@@ -336,6 +401,59 @@ okl metric           # recurrence-after-arming: defect classes that came back in
                      #   where a catching check existed but wasn't turned on
 ```
 
+## Subagents and small context budgets
+
+A full briefing costs roughly **4,400 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
+already made."
+
+`--format actions` solves it by dropping everything except the imperative list:
+
+```bash
+okl check --task "add an endpoint returning an order for the logged-in user" \
+  --format actions --limit 3
+```
+
+```
+OKL — 3 rule(s) apply before you start:
+- FIX: Missing ownership scope check is an IDOR (CWE-639) [when: an endpoint fetches an
+  entity by id with no owner/tenant predicate]
+  -> add the caller's owner id to the WHERE clause; return 404 (not 403) on no match
+...
+```
+
+**Measured on this repo's own store:** ~240 tokens at `--limit 3`, ~390 at `--limit 5`,
+~630 at `--limit 8`, against ~2,650 for the full briefing. Cheap enough to call per subtask.
+
+The full briefing is itself capped: `check` keeps the top `--limit` records (12 by
+default) from the ranked, filtered set and says how many it trimmed. Before that cutoff
+existed, one task on this store returned 20 records and ~4,400 tokens. Re-running the A/B
+after adding it showed no retrieval miss — the one task that regressed still had its rule
+in the briefing and the model simply did not follow it, which is a compliance problem
+rather than a retrieval one. See [evals/REPORT.md](evals/REPORT.md).
+
+What it drops: the bucketed sections, the prose bodies explaining *why* each record
+exists, prior-art notes, and the stale-record footer. What it keeps is what changes
+behaviour: the verb, the symptom to watch for, and the fix.
+
+**Wiring it into a subagent.** Three ways, in order of how much enforcement you get:
+
+1. **The MCP tool** — `okl_check(task=..., compact=True, limit=3)`. Any subagent with
+   MCP access can call it. Discretionary: the agent has to choose to.
+2. **In the subagent's prompt** — have the spawning agent run `okl check --format
+   actions --limit 3` and paste the result into the subtask description. Not
+   discretionary, and it costs the parent almost nothing.
+3. **A wrapper script** that runs the check and prepends it to whatever prompt it is
+   handed. This is the enforced version for orchestration you control.
+
+**A caveat worth stating.** `--limit` caps how many records the briefing draws on, and
+ranking decides which survive. If a task's most relevant rule ranks fourth and you ask
+for three, you will not see it, and nothing will tell you. The full briefing exists
+because it does not make that trade. Use the compact form where a token budget forces
+the choice, not by default.
+
 ## Verification: don't let a step grade itself
 
 A step reporting "I succeeded" and the work actually being done are two different facts,
@@ -371,17 +489,36 @@ folder.) Two clarifications that stop the common misreadings:
 
 ## Seed it (so the very first `check` returns something)
 
-An empty store returns nothing. You can hand-`record` your first lessons, or load a
-starter file — a JSON list of notes and links:
+An empty store returns nothing, and says so — a check against an empty store reports
+that it proved nothing rather than reporting "no rules apply". Three ways to fill it:
+
+**1. See what ships, then choose.** A bare `okl seed` imports nothing; it lists the
+bundled packs with their record counts and subject tags, marking the ones that match
+this repo's declared interests:
 
 ```bash
-okl seed seed/react-defects.json      # or point at a directory to load several
+okl seed                              # list the packs, import nothing
+okl seed <path>/rag-defects.json      # import one
+okl seed --all                        # import every pack (explicit on purpose)
 ```
 
-The bundled seed files hold real, dated lessons from a few production codebases
-(a .NET service, a geospatial ML pipeline, a Python search service, a React app).
-Treat them as examples of the format and as genuinely useful starting defects; delete
-what doesn't apply to you.
+The packs hold real, dated records from production codebases (a .NET service, a
+geospatial ML pipeline, a Python RAG service, a React app). They are org-scoped, so
+importing packs for stacks you do not use fills every briefing here with noise about
+frameworks you will never touch — which is why `--all` is opt-in rather than default.
+
+**2. Generate records from this codebase.** If you use a coding agent, the scaffold
+stamps a `/seed-from-codebase` command that has the agent read your repo — the guard
+rails already in the code, what CI enforces, the fix commits, the existing canon — and
+propose records with a `file:line` citation each. Everything it proposes is repo-scoped
+and unverified by design; it writes a reviewable file and imports nothing, because a
+plausible rule no file supports is worse than an empty store.
+
+**3. `okl bootstrap`** greps git history and file names for candidates. It is the weakest
+of the three and comes up empty on young repos; prefer option 2 when an agent is available.
+
+Whichever you use, review before importing. Choosing a record's scope is the curation
+step that keeps a shared layer from filling with one project's noise.
 
 ---
 
@@ -412,14 +549,8 @@ TDD, plan writing/execution, git-worktree isolation) are **not bundled** — the
 best maintained in third-party collections, so `skills/RECOMMENDED-COMPANIONS.md`
 points at those instead of vendoring someone else's work and its cross-references.
 
-The scaffold is independent of the knowledge store — use either half on its own.
-
-## The two halves
-
-| Piece | What it is | Where it lives |
-|---|---|---|
-| **client** (`okl` CLI + agent tools) | `check` / `record` / `search` / `link` / `drift` / `seed` / … | installed per-repo (this package) |
-| **shared layer** (`okl serve`) | a small web service that owns the database, so many repos share one store | one place you run it |
+The scaffold runs with no store at all; the store works in a repo that never scaffolded.
+They are complementary, not a package deal.
 
 **Storage is swappable** via one environment variable — your commands never change:
 
@@ -435,17 +566,19 @@ okl serve --port 8080
 
 ```bash
 pip install "org-knowledge-layer[service]"
-OKL_DATABASE_URL="sqlite:///okl.db" OKL_TOKEN="a-shared-secret" okl serve
+OKL_DATABASE_URL="postgresql://user:pass@host/okl" OKL_TOKEN="a-shared-secret" okl serve
 # repos then: okl connect https://your-host --token a-shared-secret
 ```
 
-`OKL_TOKEN` (optional) gates **writes**; **reads stay open** — `/nodes` returns the
-whole store to anyone who can reach the port. A mature store holds your defect history,
-security patterns and internal architecture, so treat it as sensitive: bind it to a
-private network or put authentication in front of every route before exposing it. See
-[SECURITY.md](SECURITY.md). Deploy the service
-wherever you like — it's storage-agnostic by design (a `Dockerfile` and a
-`fly.toml` are the obvious next commit; not included in v0).
+**Set `OKL_TOKEN`.** With it, every route requires the bearer token except `/health`
+(left open so schedulers can probe it). Without it, every route is open — including
+`GET /nodes`, which hands the whole store to anyone who can reach the port. A mature
+store is a catalogue of your known defects and internal architecture, which is a map of
+where you are weak. It is a single shared secret with no per-repo scoping or rotation;
+put a real authenticating proxy in front if you need more.
+
+Full instructions, including a throwaway Postgres for trying it locally and what the
+failure modes look like: **[docs/DEPLOY.md](docs/DEPLOY.md)**.
 
 ## Agent integration (MCP)