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…
In this repository4 other files it gives its agents.
- AGENTS.mdAGENTS.md
- gatesSkill
- reconcile-backlogSkill
- verify-ticket-premiseSkill
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
- Distinctive: line 25
Never hardcode a version in a workflow.
- Very specific: line 94
Before opening a PR, use the gates skill — it enumerates gates from the workflows rather than from memory.
- Very specific: line 100
Use the verify-ticket-premise skill.
- Very specific: line 108
Public repo: No private tracker ids or links in commits, PR text, code, comments or changes/ fragments.
- Distinctive: line 114
Tests first: Write the new or changed test, show it failing for the right reason, then fix.
- Distinctive: line 115
Put that failing output in the PR body.
- Distinctive: line 250
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 …
- Very specific: line 302
Read .entire/agent-guide.md for this repository's workflow, source inspection, and verification guidance.
≈ “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.
Files
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
| pin | source of truth | |
| Bun | 1.4.4 | mise.toml + packageManager in package.json — must agree |
| Node | 26.12.1 target / 24 supported floor | mise.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 |
| Python | 3.14 | mise.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) |
| Rust | 1.99.1 exact | packages/native/rust-toolchain.toml |
| TypeScript | 7.0.2 | root + packages/*. docs/ is a separate install root (Mintlify site, no TypeScript of its own) |
| Vitest | 5 | AST-aware coverage remapping is mandatory in v4 — numbers are not comparable to v3 |
| Biome | 2.6.3 | format + 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-smokeTargeted 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-textenforces it. A GitHub issue number (Refs #123) is fine. - One PR per task, branched from
origin/mainin its own worktree. Commit with DCO sign-off (git commit -s). Add achanges/<slug>.mdfragment (format inchanges/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
gatesskill (the CI lint job runs ~21 steps;bun run lintis only biome). Mind thecheck:comment-styleratchet and biome's 700-line ceiling. - Before pushing: merge
origin/mainby hand (resolve conflicts yourself, never by script), then runledger replayas its own command and push separately. - Local tests = the diff; the full suite = CI. Locally run your targeted files plus
bun run test:relatedinpackages/server(every test that imports a changed file, viavitest run --changed origin/main; a config orpackage.jsonchange runs everything). Put that, not the full suite, in the ledger. The full suite runs in CI on three OSes; when it fails there, runpr-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), neverpkill/killallby 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.
| file | regenerate with |
docs/reliquary-tc.config.schema.json | bun run config:schema |
packages/server/src/db/migrations-embedded.ts | bun 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:
| what | where it lives now |
| structural map: scale, per-subsystem counts, largest files, import graph | bun 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 index | gitignored 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 prose | not stated anywhere; docgen:facts-check forbids the count. Tool names: packages/server/test/registered-tools.txt. |
| release notes | changes/<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 todb/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; seecitation.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 --compilebakesimport.meta.urland embeds no assets. That is why migrations are codegen'd into a.tsmodule. AnyreadFileSyncof a.sql/.jsonasset 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.ymlandci-docgen.ymlare 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 apaths: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:
- The registered-tool names manifest —
test/registered-tools.txt, one name per line, sorted.test/tool-count.test.tsdiffs the live registry against it and names the tool that is missing or extra. There is no count literal to bump:REGISTERED_TOOL_COUNTis derived from the file. - The facade domain map —
test/tool-facade-domain-coverage.test.ts. Reusing an existingdomainonly trips its count assertion (its count is derived fromregistered-tools.txt); a new domain is what makes the map itself load-bearing. boot.tools_registered—eval/perf/baseline.small.json, hard/exact. Pinned 4 lower than the number of names inregistered-tools.txt, sincehealth,index_status,get_task_statusandcancel_taskregister inline incli.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 —manifestExpectationsineval/perf/gate.ts) and ignores the number recorded in the baseline, so a stale recorded value no longer fails the post-mergeperfjob. 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 everyexactvalue 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_mswas then compared against a 148-tool figure for 13 days, and read +70.6% when finally re-recorded — none of it a regression. Anexactkey fails loudly so it stays current and looks like evidence; thewarnkeys beside it rot silently.- 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) anddocgen:render -- --check(regions still canonical-empty, every target still renders): they are separate gates and running one is not running the other. The m7 metadata parity snapshot, if the tool lives in
m7/knowledge—test/m7-tool-metadata-parity.test.tspins 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 inbuildKnowledgeToolsmoves it by construction. It is an inline literal rather thantoMatchSnapshot()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.unionoutputSchema (theavailableWithenvelope) snapshots asoutputKeys: []—topLevelShapereturnsundefinedfor 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 justsafeParsesuccess: 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):
pathAcl, or a documented exemption —test/acl-extraction-coverage.test.ts. A mutating tool that names no caller-controlled vault path belongs inEXEMPT_NO_PATHwith a comment saying why. Being vault-scoped and naming a path inside a vault are different things; only the second ispathAcl's business.
If it also takes a vault:
vaultArg, and the field must be the brandedVaultId—test/vault-arg-coverage.test.ts. The gate recognises a vault-shaped field by that schema, sovault: 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:
- biome's 700-line
noExcessiveLinesPerFile— three tools tookexperiential-tools.tsto 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 -->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
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.

