agentleFS
The-40-ThievesThe-40-Thieves/obsidian-tc/CLAUDE.md

obsidian-tc

CLAUDE.md13 starsChanged 5 days agoApache-2.0View on GitHub

An MCP server over Obsidian vaults. Bun + TypeScript monorepo with a Rust native addon and two Python model services. @types/node is on ^26 (owner decision 2026-10): types target Node 26, the runtime floor stays engines.node: ">=24" and is enforced by CI running on 24. The cost is deliberate and known — a Node-26-only API now compiles, so the Node 24 CI leg (not the typechecker) is what catches it. Rust pin trap: dtolnay/rust-toolchain does not read rust-toolchain.toml. Pinning only…

The file

We split this CLAUDE.md into the rules it gives an agent

8 rules. About 0 are common, 4 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Never hardcode a version in a workflow.

    line 25
  2. Very specific:

    Before opening a PR, use the gates skill — it enumerates gates from the workflows rather than from memory.

    line 94
  3. Very specific:

    Use the verify-ticket-premise skill.

    line 100
  4. Very specific:

    Public repo: No private tracker ids or links in commits, PR text, code, comments or changes/ fragments.

    line 108
  5. Distinctive:

    Tests first: Write the new or changed test, show it failing for the right reason, then fix.

    line 114
  6. Distinctive:

    Put that failing output in the PR body.

    line 115
  7. Distinctive:

    Docs: nothing to edit, two gates to run: No doc prose states the tool count any more, and the tool catalog and its marker regions are …

    line 250
  8. Very specific:

    Read .entire/agent-guide.md for this repository's workflow, source inspection, and verification guidance.

    line 302

≈ “Common” is an estimate: at least 1 in 5 of the 28,029 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

reliquary-tc — working notes for Claude Code

An MCP server over Obsidian vaults. Bun + TypeScript monorepo with a Rust native addon and two Python model services.

Toolchain — pinned, do not float

pinsource of truth
Bun1.4.4mise.toml + packageManager in package.json — must agree
Node26.12.1 target / 24 supported floormise.toml; engines.node: ">=24". CI runs the full server suite on both 26 and 24 (build-test, fallback-test) — the 24 legs catch a 26-only API
Python3.14mise.toml; bge-m3-service declares requires-python = ">=3.12" (its runtime lock pins numpy 2.5 and scipy 1.18, which need 3.12) and docs-ingest ">=3.14" (the version CI tests; the floor was raised from 3.11 so the lock stops carrying old-Python-only package versions such as soupsieve 2.10)
Rust1.99.1 exactpackages/native/rust-toolchain.toml
TypeScript7.0.2root + packages/*. docs/ is a separate install root (Mintlify site, no TypeScript of its own)
Vitest5AST-aware coverage remapping is mandatory in v4 — numbers are not comparable to v3
Biome2.6.3format + lint; there is no ESLint/Prettier here. 2.6 formats and lints Markdown and YAML by default: biome.json turns both off so the scope matches 2.5

@types/node is on ^26 (owner decision 2026-10): types target Node 26, the runtime floor stays engines.node: ">=24" and is enforced by CI running on 24. The cost is deliberate and known — a Node-26-only API now compiles, so the Node 24 CI leg (not the typechecker) is what catches it.

Rust pin trap: dtolnay/rust-toolchain does not read rust-toolchain.toml. Pinning only the file splits cargo's toolchain from the one targets install onto → E0463: can't find crate for std. .github/actions/setup-rust parses channel out of the file and passes it as toolchain:. Never hardcode a version in a workflow.

Workspaces

packages/server · packages/shared · packages/native (napi-rs) · packages/plugin

docs/ is NOT a workspace member and has its own docs/bun.lock. Root bun install, overrides, and bun audit do not reach it — a root audit has already missed 6 advisories that lived only there.

Commands

bun run lint        # ONLY biome. It runs no check:* gate — see below
bun run typecheck   # all four packages, PLUS packages/server/tsconfig.bun-smoke.json
bun run test        # per-workspace; server is vitest under Node, native is cargo test
just                # list recipes (build, test, lint, format, bundle, map, release)

bun-smoke/ is a SEPARATE tsc project (packages/server/tsconfig.bun-smoke.json). It is not in the main config's include, because it is the only code allowed to see Bun's globals — src/test pin types: ["node"] so they keep compiling against the Node floor that build-test runs on. Before it was wired in, bun run typecheck reported 0 while nine bun-smoke files did not compile, and CI's bun-smoke job found them as runtime failures instead. If you change a signature in the vec/indexing path, the bun-smoke project is what catches those call sites.

bun run lint is biome check and nothing else. The gates run as separate steps of CI's lint job, which is a different thing with a confusingly similar name. Green locally on bun run lint says nothing about them. Enumerate the real list from .github/workflows/ — the lint job currently runs biome plus check:boundaries, check:dev-dep-imports, check:perf-timing-scope, check:ingest-telemetry-wiring, check:config-paths, check:comment-style, check:plugin-routes, check:public-text, check:readme-size, check:duplicate-exports, check:table-readers, check:embedding-transport, test:scripts, check:duplication, check:export-surface, check:facade-parity, check:model-fetch-parity, check:model-pins, check:acl-identity and check:tool-description-acks (21 steps; the Python under packages/server/eval has its own python-eval job; this list read ten until 2026-09-26, and the eleventh cost a CI round).

check:comment-style is a RATCHET on the COUNT of files with >= 120 comment lines (scripts/comment-style-baseline.json, maxFiles), not a per-file cap. A file sitting at 119 on main fails the job the moment a new docblock lands in it. On failure the gate lists every offending file with its count, marking each one not already over the threshold on origin/main as new (with main's count) — see the gates skill for the exact shape. Prefer trimming the new/grown block back under the threshold over raising maxFiles.

check:config-threading is NOT a script — do not try to run it. No such entry exists in either package.json. The config-threading gate lives in ci-security.yml, which invokes the file directly: node scripts/check-config-threading.mjs. Enumerating gates from package.json misses it entirely, and bun run check:config-threading fails with "Script not found", which reads as a failing gate rather than a missing one.

check:merge-driver is in package.json and no workflow invokes it — deliberately. It verifies merge.*.driver in .git/config, which git never commits or clones, so CI can only either re-check the setup it just ran (tautological) or fail on every fresh clone. It is a local diagnostic, run via prepare on install and available as just check-merge-driver. Leave it out of CI.

The general rule still holds — a script existing is not a gate running, and a gate running is not always a script. Grep the workflows, not package.json, and expect both directions to differ.

Don't run the full suite locally. This box is 4 cores shared with ~43 containers; GitHub-hosted runners are free and unmetered for public repos, and cover three OSes:

gh workflow run ci-server.yml --ref <branch>     # lint + build-test (3 OS) + bun-smoke

Targeted vitest and bun run test:related stay local. Anything heavy that must run here goes through scripts/with-host-budget.sh (or bun run test:local in packages/server) — it serialises concurrent runs with flock and caps CPU at 2.5 of 4 cores, leaving the rest for the services.

Before opening a PR, use the gates skill — it enumerates gates from the workflows rather than from memory. Two scripts have confusingly adjacent names (check:config-paths ≠ config:schema:check) and substituting one for the other has cost a CI round.

Before implementing a ticket

Use the verify-ticket-premise skill. Tickets here go stale fast: in one session, five had premises that no longer held — one was entirely already done, another quoted a duplication rate 660× the real one. The check costs minutes; acting on a stale premise has cost days.

Every change: the working rules

These hold for every PR, so a task brief does not repeat them.

  • Public repo. No private tracker ids or links in commits, PR text, code, comments or changes/ fragments; check:public-text enforces it. A GitHub issue number (Refs #123) is fine.
  • One PR per task, branched from origin/main in its own worktree. Commit with DCO sign-off (git commit -s). Add a changes/<slug>.md fragment (format in changes/README.md, no PR number).
  • Install with bun install --frozen-lockfile --ignore-scripts; a plain install fails on the better-sqlite3 build script and is not needed for any gate.
  • Tests first. Write the new or changed test, show it failing for the right reason, then fix. Put that failing output in the PR body.
  • Gates come from the gates skill (the CI lint job runs ~21 steps; bun run lint is only biome). Mind the check:comment-style ratchet and biome's 700-line ceiling.
  • Before pushing: merge origin/main by hand (resolve conflicts yourself, never by script), then run ledger replay as its own command and push separately.
  • Local tests = the diff; the full suite = CI. Locally run your targeted files plus bun run test:related in packages/server (every test that imports a changed file, via vitest run --changed origin/main; a config or package.json change runs everything). Put that, not the full suite, in the ledger. The full suite runs in CI on three OSes; when it fails there, run pr-doctor <pr> (it prints the failing test and assertion), fix from that, and push. Do not re-run the whole suite locally to find a failure. Import-graph selection misses tests that read source as text (source scans, fixtures); that is the gap CI covers.
  • Never git stash (the stash is shared across worktrees; use a temporary commit), never pkill/killall by pattern (it hits other runs), never force-push.
  • Report back with the PR number, head SHA, a table of what was done and how it was proven, test counts, the failing-first evidence, and anything you did differently from the brief.

Generated artifacts — never hand-edit

A PreToolUse hook blocks these; the message names the regeneration command.

fileregenerate with
docs/reliquary-tc.config.schema.jsonbun run config:schema
packages/server/src/db/migrations-embedded.tsbun run migrations:embed

The list lives in .claude/generated-paths.txt (<path>, a TAB, <regenerate command>), the one source of truth. .claude/hooks/block-generated-edits.sh blocks Edit/Write on exactly those paths (a path named only in the script is not blocked). .claude/hooks/generated-drift-backstop.sh (PostToolUse, Bash) catches the shell-write routes no pre-parser sees and says to git checkout -- <path> and rerun the generator. permissions.deny in .claude/settings.json needs an Edit(/<path>) rule per entry (scripts/claude-hooks.test.mjs checks it). To protect a new generated file, add one line to the txt and the deny rule.

Most generated content is no longer committed at all, because anything that moves whenever an unrelated file moves makes every pair of PRs conflict on it. Nothing to hand-edit, nothing to regenerate before a commit:

whatwhere it lives now
structural map: scale, per-subsystem counts, largest files, import graphbun run map writes the gitignored generated/tree-map.md + generated/dependency-graph.json. TREE.md is hand-written prose. bun run map:check (drift-gate) only proves the generator runs and that nothing generated is committed again. Graph stability depends on both inputs coming from git ls-files and tsconfig.dependency-cruiser.json pinning the shared package to packages/shared/src, so untracked build output does not affect either command.
decisions indexgitignored docs/src/content/docs/contributing/decisions-index.md, written by bun run docs:decisions-index (docs gen does it). docs:decisions-index:check fails if a committed copy exists.
docgen marker regions (<!-- BEGIN GENERATED: ... -->)committed canonical-empty. bun run docgen:render fills them (docs build, wiki publish), -- --reset empties them, -- --check is the gate and fails on any filled region. Never commit a filled one.
tool and domain counts in prosenot stated anywhere; docgen:facts-check forbids the count. Tool names: packages/server/test/registered-tools.txt.
release noteschanges/<slug>.md fragments, folded into CHANGELOG.md at release (bun run check:changes). Write it WITHOUT the PR number (the release adds (#N) from the merge history; never commit it after opening the PR). Do not edit [Unreleased].

migrations-embedded.ts and the config JSON Schema stay committed. migrations-embedded.ts is the one generated file two PRs can still both change; .gitattributes gives it the regen merge driver (scripts/merge-drivers/regen.mjs, registered by bun install's prepare, checked by bun run check:merge-driver). GitHub's own conflict check ignores merge drivers, so merge or rebase main locally to resolve such a conflict. A change to an existing config key's type, default or constraint needs config-schema-change: <key> in its changes/ fragment.

Advertised tool names and descriptions are gated, because clients key approvals to them. claude.ai keys "Always allow" to a hash of the description and Visual Studio resets approvals on list_changed, so rewording a description makes every user re-approve that tool. A description change therefore needs three things: bun run tool-descriptions:update in packages/server (rewrites test/tool-descriptions.snapshot.json: full text, sorted, one <surface>/<tool> entry per line; test/tool-description-snapshot.test.ts fails on a stale one), the changed tool named in tool-description-change: <tool>[, <tool>] in the changes/ fragment (check:tool-description-acks, a lint-job step, diffs the snapshot against origin/main; a new or removed tool needs nothing), and the domain-mode entry follows from its members (the member's name acknowledges its line). Names: test/tool-name-hygiene.test.ts holds every advertised name on every surface to at most 40 chars, ^[a-z][a-z0-9_]*$, no generic name (read, run, get, ...) unless allowlisted with a reason in scripts/docgen/check-tool-names.ts (search/fetch are the standard OpenAI names: never rename), and one meaning per name across surfaces. The server emits no list_changed at all; test/list-changed-stability.test.ts keeps it that way.

Which docs carry marker regions is GENERATED_DOC_FILES in packages/server/scripts/docgen/targets.ts; render.ts asserts its own targets against it. Do not count them by grepping for BEGIN GENERATED (that also hits this file, which names the string in prose). Edit the prose around a region freely; never put content inside one.

Conventions that bite

  • Migrations are append-only, hand-registered, checksum-pinned. Add the .sql, append it to db/migration-manifest.ts, regenerate the embedded copy. Editing a shipped migration is a hard startup error. There is no down-migration and no dry-run.

    There is a FOURTH step, and nothing gates it: just migration-impact <file.sql>. Those three steps are all gated (migrations-manifest.test.ts, migrations:embed:check) — the test suite is not. 62 test files hand-build their own literal migration chain; only 16 read the manifest. A new migration leaves all 62 behind, and without this lookup you find the affected ones one red CI build at a time — that cost three separate rounds on 2026-08-06. The duplication is deliberate (a minimal chain makes a test's schema dependencies explicit; see citation.test.ts's own note), so the fix is knowing the set, not collapsing it. It prints the chains that CREATE the table your migration touches; not all of them will break, it is the set to CHECK.

  • bun --compile bakes import.meta.url and embeds no assets. That is why migrations are codegen'd into a .ts module. Any readFileSync of a .sql/.json asset ships a binary that only runs on the build machine.
  • Never pipe a gate through tail/head — $? reports the pipe, not the command. This has masked a failing suite and a failing lint. Redirect to a log; check $? separately.
  • Parallel agents need separate worktrees. git worktree add <dir> -b <branch> origin/main. Two agents in one checkout silently interleave edits.
  • ci-server.yml and ci-docgen.yml are deliberately unfiltered. A required status check whose workflow is path-filtered leaves the PR blocked forever on "Expected — waiting for status to be reported." Do not re-add a paths: filter to either.
  • A new gate must be watched failing before it is trusted, and needs a non-empty floor. A gate that has never failed proves nothing; one that scans zero files reports success.

Adding a tool moves eight things

Five always, three more if the tool mutates or takes a vault. Measured 2026-08-03 adding three tools (154 → 157): the first four were known, CI caught the last three, and a local sweep that skipped bun run lint at the repo root missed two of those. Item 5 was added 2026-08-04 adding explain_answer (157 → 158) — this file said seven, all seven were moved, and CI failed anyway on an eighth nobody had written down.

Always:

  1. The registered-tool names manifest — test/registered-tools.txt, one name per line, sorted. test/tool-count.test.ts diffs the live registry against it and names the tool that is missing or extra. There is no count literal to bump: REGISTERED_TOOL_COUNT is derived from the file.
  2. The facade domain map — test/tool-facade-domain-coverage.test.ts. Reusing an existing domain only trips its count assertion (its count is derived from registered-tools.txt); a new domain is what makes the map itself load-bearing.
  3. boot.tools_registered — eval/perf/baseline.small.json, hard/exact. Pinned 4 lower than the number of names in registered-tools.txt, since health, index_status, get_task_status and cancel_task register inline in cli.ts.

    Nothing to do when adding a tool. The perf gate takes the expected value for this key from registered-tools.txt (names minus the four inline tools, exact equality — manifestExpectations in eval/perf/gate.ts) and ignores the number recorded in the baseline, so a stale recorded value no longer fails the post-merge perf job. Do NOT hand-edit the baseline copy. Re-record it (perf-baseline.yml, commit all three files) only when the timing keys need re-recording anyway; editing this key in place fails the baseline coherence check: the provenance sidecar snapshots every exact value at record time, and a mismatch means the timing keys beside it were measured against a different tool surface.

    That check exists because hand-editing was the documented advice here until 2026-08-08, and it produced exactly the failure you would expect. Between 07-27 and 08-05 this key was bumped seven times (148 → 157) while every boot.* timing stayed frozen at what 148 tools cost, sitting inside a 0.5 warn tolerance where nothing could see it. boot.tools_list_ms was then compared against a 148-tool figure for 13 days, and read +70.6% when finally re-recorded — none of it a regression. An exact key fails loudly so it stays current and looks like evidence; the warn keys beside it rot silently.

  4. Docs: nothing to edit, two gates to run. No doc prose states the tool count any more, and the tool catalog and its marker regions are generated at build. Still run docgen:facts-check (forbids a count creeping back in) and docgen:render -- --check (regions still canonical-empty, every target still renders): they are separate gates and running one is not running the other.
  5. The m7 metadata parity snapshot, if the tool lives in m7/knowledge — test/m7-tool-metadata-parity.test.ts pins an ordered, byte-identical snapshot of every m7 tool's public metadata (name, description, domain, scopes, tags, hasPathAcl, and the top-level input/output keys), so a new tool in buildKnowledgeTools moves it by construction. It is an inline literal rather than toMatchSnapshot() on purpose — there is no __snapshots__ dir, so an auto-written snapshot would be created-and-pass on its first run. Derive the new entry from the tool and read it back, don't hand-type it.

    A z.union outputSchema (the availableWith envelope) snapshots as outputKeys: [] — topLevelShape returns undefined for a union, correctly. That is the honest value, and it also means the parity gate stops guarding that tool's output shape, so pair it with a round-trip parse test. Compare key sets after parsing, not just safeParse success: Zod objects are non-strict, so a field with no schema entry is silently stripped and still parses.

If the tool MUTATES (destructive: true, or any write:/admin: scope):

  1. pathAcl, or a documented exemption — test/acl-extraction-coverage.test.ts. A mutating tool that names no caller-controlled vault path belongs in EXEMPT_NO_PATH with a comment saying why. Being vault-scoped and naming a path inside a vault are different things; only the second is pathAcl's business.

If it also takes a vault:

  1. vaultArg, and the field must be the branded VaultId — test/vault-arg-coverage.test.ts. The gate recognises a vault-shaped field by that schema, so vault: z.string() reads to it as a mutating tool with no vault at all and fails with a confusing message about a set you did not touch.

Whenever the target file is near the ceiling:

  1. biome's 700-line noExcessiveLinesPerFile — three tools took experiential-tools.ts to 839. Splitting is the fix, but a naive split creates a circular import (check:boundaries, baseline 0): lift the shared deps and helpers into a third module rather than having the new file import from the old one.

Run bun run lint at the REPO ROOT before committing, not biome check --write per file. The line-ceiling rule is invisible per-file, and per-file formatting leaves drift a later edit re-breaks.

Security posture

trusted-local is the default and leaves snapshots.enabled on — destructive note writes capture an undo via restore_note unless a config explicitly opts out (snapshots: { enabled: false }). Retention (10 versions/note) is pruned inline and orphan blobs are GC'd, so growth is bounded by construction. Worth knowing either way before running anything that deletes.

<!-- entire-agent:begin -->

Read .entire/agent-guide.md for this repository's workflow, source inspection, and verification guidance. @.entire/agent-guide.md

<!-- entire-agent:end -->

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.