Skip to content

Upgrade notes

What changes when you move to a new release, where a version number cannot say it.

Most releases need nothing here. Semver carries compatibility, --generate-notes carries the list of what changed, and the four layers in versioning carry which of them moved. What none of those can carry is the sentence a person needs before upgrading: your working setup will behave differently, and here is the repair.

A change belongs here when a configuration that works today stops working, or starts working differently, without the person having changed it. A new feature does not; a bug fix usually does not; a fix that makes a previously-quiet misconfiguration loud does.

How this reaches a release

A note is written as its own file in .changes/upgrading/. The version it ships in is unknown until the release is cut. Name the file <issue>-<slug>.md and open it with the note's ### heading.

Notes do not go in this file directly. Each one used to be added at the same line, so two open pull requests always conflicted.

When a tag is chosen, mise run file-upgrade-notes <tag> moves every staged note under ## <tag> here. Newest issue comes first. At release time, .github/workflows/release.yml prepends that section to the generated notes. The note then appears in the release itself.

release.sh refuses a tag while a note is still staged. An unfiled note fails silently in two ways. It is dropped from the release being cut, or it lands in a later release. The repair is to run the filing task and commit.

cli/v0.25.0

A coined property type is now reported

property-type-unknown warns on a type: that nothing reads (#1391). Its values were never checked. Known types are string, text, ref, date, number, claim, quotation and list. For entries that are records, declare a list with fields:. The finding is a warning and does not gate.

cli/v0.24.0

phase settle --merge writes the phase merge, and max_open_proposals is read locally

yidam phase settle --merge writes the merge that settle drafts. It is authored by yidam phase, with you as committer. It refuses a phase that is not ready, or a baseline that has moved on. It also refuses a checkout that is not the commit. --summary "<text>" replaces the drafted tally in the merge subject. Plain yidam phase settle is unchanged and still commits nothing.

[cluster] max_open_proposals is now read by yidam propose and yidam run, against local propose/* branches. At the cap, neither opens a new proposal branch. A corpus without the key sees no change. See cli-reference.md and configuration.md.

New derivations may write proposals, where an identity allows it

New derivations ship [serve] act = "when-identity" in .yidam/config.toml. serve --mcp then serves propose and cycle wherever a git author identity resolves. Without one, the server still starts, with the read tools only. It says why at startup and in every refusal of propose or cycle. An HTTP bind beyond loopback is treated the same way.

An existing repository keeps what its file says. Write act = "when-identity" under [serve] to adopt the new default. act = true still refuses to start where a condition fails.

The MCP contract is now 0.32.0.

Sessions now open with the loop's brief

New derivations ship .claude/settings.json with two Claude Code hooks. The SessionStart hook prints yidam cycle --brief into the session. The Stop hook records the round and tells you what each turn moved.

Run yidam migrate scaffold to add the hooks to an existing repository. It creates .claude/settings.json, or adds the hooks to yours. It refuses a settings file that already declares hooks. Add the two entries by hand there, as sadhana/root/claude-settings.json does.

yidam doctor warns when a repository with a CLAUDE.md has no hooks. The hooks run the binary in .yidam/bin, so pin a release that has yidam hook. An older binary makes the hooks silent, never a failure.

cycle can now say what moved since the last round

yidam cycle --record keeps this round under .yidam/loop/<branch>.json. yidam cycle --since-last reports what arrived and what left since that record. It covers findings, due clocks, stale steps, refs in flight and local proposals. Each branch keeps its own record, and a detached HEAD keeps HEAD.json.

The directory writes its own .gitignore, so nothing in it is ever staged. No migration is needed.

With no record, since_last is absent and since_last_unread says why. Never read that as nothing having moved.

yidam cycle --brief prints a short report within a token budget. The default budget is 500 tokens, and --budget changes it. It refuses --format json.

Without these flags, cycle prints exactly what it printed before.

cycle acts now say whether a command does them

Each act in cycle's next, and each clock naming a remedy, now carries kind. It is tool or person. A tool act carries argv, and running it from the report's root is the act. A next item also carries targets, naming the nodes, steps or refs it is about.

A loop can now run tool acts without parsing the prose act string. Treat a missing kind as person, because an older yidam sends none.

The MCP contract is now 0.31.0. Its cycle notes now also describe stale_steps and stale_steps_unread.

cycle now reports stale manifest steps as owed

yidam cycle now reads .yidam/capabilities.toml the way yidam run --dry-run does. A step whose receipt does not match the tip is listed under stale_steps. It adds one yidam run act to next.

cycle --strict now exits nonzero on a stale step, as it does on a due clock. A scheduled job using --strict may start failing where it passed before. Run yidam run, or drop --strict if you only wanted the report.

When the steps cannot be planned, stale_steps_unread says why. A detached HEAD is the common case, so CI checkouts will see it.

cycle now spells an in-flight act in_flight

next[].source for an in-flight phase is "in_flight". It used to be "inflight" (#1439). The schema always declared "in_flight", so a validating consumer rejected any cycle report with a phase in flight.

If you match on source, match "in_flight". This applies to a script or a prompt that reads cycle --format json or the MCP cycle tool. A match on "inflight" will stop finding anything.

cli/v0.23.1

The bootstrap skill is no longer vendored

A re-vendor now removes .yidam/.vendor/prelude/skills/ (#1435). The bootstrap skill made your repository and never runs in it again.

Delete the bootstrap row from .yidam/skills/README.md by hand. It sits under Inherited from prelude, and its link now goes nowhere. A re-vendor never rewrites that file, so nothing else will remove it. Delete the whole table if that row was its only entry.

cli/v0.23.0

index-build embeds each record alone

index-build now embeds one record per call (#1428). Each record is embedded the way a query is. Before, records went in batches of 256. Each vector then depended on the records batched with it.

Rebuild your index with yidam index-build. An old index still works, but its vectors sit slightly apart from its queries. On one corpus, a record used as a query kept 92% of its top ten.

A shared remote index should be rebuilt by every corpus that pushes to it. Then all its vectors come from one build.

The build is also faster and smaller. One corpus took 23 seconds instead of 43, and 0.2 GB instead of 12 GB. [index] batch_size restores batching, but its vectors drift from the queries again. See configuration.

cli/v0.22.0

type: list is now a checked type

A property declared type: list is now read (#1391, RFC-0050). Before, list was a coined type and nothing checked it. Its value must now be a non-empty list. A single value not wrapped in a list is reported by property-type.

items: and fields: say what each item is. fields: declares a record, closed to keys it does not name. A misspelled key in a record is now an error. See configuration for the forms.

A tag inside a property is no longer the node's standing (#1382). Standing is read from top-level type: claim properties only. To grade each entry, declare the property type: list with a claim field. claim-property-undeclared now suggests exactly that.

The warehouse contract no longer refuses a list property. It gets no column, as a claim does.

cli/v0.21.0

Semantic retrieval is in every released binary

vector-read joined the default feature set (#442). Every install channel now carries index-build and semantic retrieve. yidam --version lists vector-read index among its features. The binary grows from about 23 MB to 56 MB.

What changes for you: retrieve turns semantic once the corpus has an index. Run yidam embed && yidam index-build, or yidam vault pull --index where a vault holds one. A corpus with no index answers by keyword, as before. Semantic retrieval does not span tonpa dependencies; keyword retrieval does.

On an Intel Mac, install ONNX Runtime 1.24 or newer. brew install onnxruntime provides it. The Homebrew tap installs it for you. Elsewhere set ORT_DYLIB_PATH to a libonnxruntime.dylib. Without it, only commands that embed fail, and each names the fix.

On Linux, the release binaries now need glibc 2.39 or newer. Debian 13 and Ubuntu 24.04 qualify. Debian 12, Ubuntu 22.04 and RHEL 9 do not, and fail with version GLIBC_2.39 not found. The cluster image moved to Debian 13 for the same reason.

To keep the old build, install from source. Pass --no-default-features with the other default features. Installation has the command.

cli/v0.20.0

Export an ontology to BigQuery and TextQL

yidam export --format warehouse writes your ontology as a BigQuery contract (#1394). It writes one table per class, a link table per edge and a value table per closed set. The first export writes ddl/bigquery/0001_init.sql. A later export writes the next numbered migration, and refuses a change that would lose data.

A feed maps a pipeline's landing table onto the contract. Declare one in .yidam/warehouse/feeds/<feed>.yml, and the export writes a MERGE script per table. It refuses a feed that maps anything the ontology does not declare.

--with-corpus adds your nodes as rows, and --format textql writes a TextQL Ontology folder. See From a corpus to a warehouse for the whole route.

What changes for you: nothing, until you run the export. Never run a snapshot feed over an empty landing table, because it deletes every row that feed wrote.

cli/v0.19.0

catalog-location-malformed reports a url with a # fragment

A url location that names a member with # is now a finding (#1352). A fragment never reaches the server, so catalog-fetch downloads the whole file. The entry then reads as if it held only the part the fragment names. The finding names the file actually fetched.

What changes for you: a corpus holding such a location gets a new warning. Move the part after # under members: to read one file inside a zip. See Read a file inside a zip.

A file inside a zip is read as a reading

A location can list members:, paths inside the zip it names (#1351). catalog-extract unpacks each into the cache and records it under the zip's readings:. Each such reading carries member: and by: unzip. See Read a file inside a zip.

Lint refuses a member path that leaves the archive. catalog-location-malformed names a path with .., a leading /, a drive letter or a backslash.

What changes for you: nothing. An entry without members: reads as before.

Source packs that pin a mutable identifier

A scheme can pin an identifier that names a moving target (#1343). Declare [scheme.<name>.pin] with mutable, read, media, value and pinned. source add asks the read once, and writes the version it answered into the identifier. See Source packs.

archive 0.2.0 adds github and wikipedia. github:<owner>/<repo>@<ref>/<path> is pinned to the commit the ref names. wikipedia:<lang>/<title> is pinned to the article's current revision. A bare wayback:<url> is pinned to the capture the archive names.

catalog-fetch refuses the mutable form, with how to pin it. It never asks the read.

The MCP contract is now 0.30.0. resolve_source returns the pinned identifier in locations, and answered counts the read.

What changes for you: re-pin archive to use the new schemes. archive@^0.1 does not admit 0.2.0. Change it to archive@^0.2, then run mise run yidam-vendor-update. Every wayback:<timestamp>/<url> location resolves as before.

Source packs that read a listing or a catalog

A scheme can resolve through a page that lists its files (#1342). Write resolve = { listing = "…", match = '…' }, or resolve = { dcat = "<host>" } for a DCAT-US data.json. Use one where a release date or a fresh path in the address defeats a template. See Source packs.

source add writes the file it picked into the identifier. The location reads scheme:local-id@<pin>, and catalog-fetch follows only the pin. An identifier in such a scheme without a pin is skipped, with a message saying how to pin it.

A resolve without template now parses. A pack with no template, listing or dcat still fails source check, now with that message.

The MCP contract is now 0.29.0. resolve_source returns the pinned identifier in locations, and answered counts a page read.

What changes for you: nothing. Every template pack resolves as before.

Source packs that read a paged answer to its end

A scheme can declare paginate (#1341). Name the offset parameter, the record array, and how to know the last page. catalog-fetch asks for every page, and records one artifact holding every record. See Source packs.

catalog-fetch refuses an answer with exceededTransferLimit: true from a scheme without paginate. The refusal is a finding on the entry, and the run fails.

What changes for you: nothing, unless an entry fetched a cut-short answer. Such an entry recorded the first page only. Declare paginate on its scheme, and fetch it again.

catalog-location-malformed checks identifiers against your packs

Once you enable a source pack, identifier locations are held to it (#1328). yidam lint reports a scheme that no enabled pack declares. It also reports a local id that the scheme's pattern refuses.

When a template pack declares the scheme, the finding names that pack. For example, wayback: names archive. Pin it under prelude_sources to clear the finding.

What changes for you: nothing, until you pin a pack. A corpus with no packs is checked for the scheme:local-id shape alone, as before.

doctor checks that your binary was built at the pin

yidam doctor has a new commit check (#1324). It compares the running binary's build commit with .yidam.toml's commit. They agree when one hash is a prefix of the other.

What changes for you: a stale .yidam/bin/yidam now fails doctor. That is the binary a re-vendor leaves behind when nobody rebuilt it. The finding names both commits. Run mise run yidam-build to repair it.

A repository with no .yidam/bin/yidam gets a warning instead, since another yidam answered. A binary that records no build commit also warns, because nothing can be compared.

The scholarly and archive source packs

The template ships its first two source packs (#1320). scholarly reads papers by doi:, pmc: and arxiv:, through Crossref, Europe PMC and arXiv. archive reads Wayback Machine snapshots and Internet Archive items. See Source packs.

One source add --fetch doi:… reaches a paper's open-access full text. The DOI leads to a europepmc: location, and that one to pmc: when Europe PMC holds the text. catalog-extract then reads the full text as plain text, without the reference list.

scholarly requires YIDAM_CONTACT. Every request it makes names that contact, and it waits three seconds between requests to one host.

What changes for you: nothing, until you pin a pack. Add scholarly@^0.1 or archive@^0.1 under prelude_sources, then run mise run yidam-vendor-update.

search_sources and resolve_source over MCP

serve --mcp answers two source-pack questions, and writes nothing (#1319). search_sources is yidam source search. resolve_source is yidam source add --dry-run. Both sit at a new sources tier, true where the corpus enables a pack. The MCP contract is now 0.28.0. See MCP server.

[serve] offline_sources = true answers both from the packs' recorded fixtures. Each answer says which route it took, in answered.

What changes for you: nothing, until you enable a pack. A client that pins the contract version sees 0.28.0, with sources in the capability block.

Source pack transforms, and readings: on a catalog artifact

A source pack's scheme may name a describe and an extract transform (#1318). Each is a .glu file under the pack's transforms/, run in the calculator arm's closed prelude. The binary parses the response as JSON, XML or CSV and hands the transform the parsed value. yidam source check admits each transform and runs it over the scheme's fixtures.

Transforms need the source-transforms feature, which is outside the default build. It implies calculators-gluon, and adds 3 packages and 0.12 MB over it. A build without it checks the rest of a pack, and says it did not check the transforms.

catalog-extract records a reading under readings:, not text:. Each reading names its digest, its media type, and what took it in by:. An artifact fetched from an identifier whose pack declares extract is read by that transform. A build without source-transforms reports that artifact as skipped.

What changes for you: nothing you must do. An entry that holds its reading under text: keeps it, and lint and the vault still read it. A PDF that already has a text: reading is not read again.

catalog-fetch follows identifiers through source packs

catalog-fetch now fetches a kind: identifier location through the pack declaring its scheme (#1317). An identifier no enabled pack declares is skipped, as before. See Fetching an identifier.

Every request now names the tool in its User-Agent. Set YIDAM_CONTACT to an email address or URL to add it there. A pack with contact = "required" fetches nothing without it.

A refused request now fails the run. A non-success status is recorded under refused and not retried. Before, it stopped the whole run with an error.

[transport] auth now names where each credential goes. Write { env = "VAR", header = "Name" } or { env = "VAR", query = "param" }. source check now reports a bare variable name as an error.

--archive adds the nearest Wayback capture as a pinned location. It needs an enabled pack declaring the wayback scheme.

yidam source list, search and add

yidam source add doi:… writes a draft catalog entry from a pack (#1316). It follows the scheme's then chain and records each identifier as a location. The entry is obtained: false, and its body is the pack's eight prompts, unanswered. Each entry is its own catalog: commit. --fetch then runs catalog-fetch on it.

yidam source search <pack> <query> prints the identifiers a pack's search answers with. A pack declares that endpoint in a new [search] table. source check holds it to the format. See Source packs.

Set YIDAM_CONTACT before asking a pack that requires a contact. It goes in the user agent. source list shows what each pack needs and whether it is set. --offline answers from a pack's recorded fixtures and asks nothing.

What changes for you: nothing, until you enable a pack.

Source packs, prelude_sources, and yidam source check

A source pack names a family of sources by identifier, such as doi: or pmc: (#1315). It is a directory holding pack.toml and entry.md, with optional transforms/ and fixtures/. See Source packs for the format.

yidam source check holds every pack and every pin to that format, offline. It exits nonzero on an error, so a repository that writes its own pack runs it in CI.

prelude_sources in .yidam/decisions/proposals.yml pins the packs a re-vendor copies. Write <pack>@<range>, or <pack>@<range> from <repo>@<commit> for another corpus's pack. mise run yidam-vendor-update copies each into .yidam/.vendor/sources/. It refuses a pin the pack's version does not meet, and then changes nothing.

What changes for you: nothing, until you pin a pack. A repository with no prelude_sources vendors no packs, and source check passes.

Catalog locations gain identifier, and the catalog gains four types

A catalog location can be kind: identifier, with a value of scheme:local-id (#1314). For example, doi:10.1167/tvst.8.5.14 or pmc:PMC6753881.

kind: doi and kind: pmc are still reported by catalog-location-malformed. The finding now names the fix, yidam migrate locations. Run it with --dry-run first to see each rewrite. A value that is a URL is reported and left for you to rewrite.

The catalog type set gains statute, report, standard and document. yidam lint now reports catalog-type-unknown at Warn for any other word. primary is reported too, because it names a standing, not a form. Nothing maps it for you: pick the type that fits each source.

The SDKs are no longer vendored

The SDKs moved from yidam/prelude/sdks/ to yidam/sdks/ (#1311). The prelude copy no longer carries them. The next yidam-vendor-update deletes .yidam/.vendor/prelude/sdks/, which held 66 to 377 files. It does so even when the pinned ref predates the move.

What changes for you: probably nothing. No derived repository we know of builds the vendored SDKs. If yours depends on one by path, depend on the published yidam-core crate instead. Its manifest now sits at yidam/sdks/rust/Cargo.toml upstream.

Every scaffolded CI job downloads yidam before compiling it

The privacy job and both release jobs now download a released binary first (#1308). Before, they cloned yidam and compiled it at every pin, released or not. Only the corpus job tried the download.

What changes for you depends on the file. The privacy job sits in ci.yml's YIDAM:CI region, so your next re-vendor brings it. release.yml is yours, so take the new .github/workflows/release.yml on upgrade. Its guard and bundle jobs then skip the toolchain whenever your pin has a release.

index.yml still compiles, because no release carries --features index.

A re-vendor takes the newest release, not the origin's HEAD

yidam-vendor-update now pins the newest cli/v* release by default (#1308). A release is a pin yidam-build can download, so no compiler runs. An untagged pin compiled the CLI from a clone, in every repository that took it.

What changes for you: your next re-vendor may land on a release, not on main. To keep pinning unreleased main, run YIDAM_REF=HEAD mise run yidam-vendor-update. A repository pinned ahead of the newest release is refused rather than rolled back. The refusal prints both commands: stay on main, or take the release on purpose.

yidam-vendor-status and the CI staleness report now measure against the newest release too.

A kuten profile with a populated policy slot is refused

A kuten proposes no severities, and a profile that tries is no longer read (#1305). The policy slot was parsed and then ignored, so a proposed severity reached nothing. The policy layer decides disclosure only. Nothing in it changes a check's severity.

What changes for you: nothing, unless you author a kuten profile. Every shipped profile carries proposes_overrides: [], which still parses. A non-empty list now stops kuten check with an error, and doctor warns. Both name the slot.

check-diff stops offering a candidate on a repeated suffix

Some words are no longer compared when check-diff looks for a near-miss (#1298). Such a word ends three or more of the report's type names and appears nowhere else in them. Nine error types are no longer each offered margin-of-error because they share error. The finding rows are unchanged; only the nearest lead goes.

cli/v0.18.0

index-build moves into vector-read and needs no protoc

index-build no longer writes a LanceDB table, so building an index needs no protoc (#1287). Nothing ever read that table. Every reader decodes corpus.arrow, which index-build now writes directly.

index-build is now in the vector-read build. index is kept as an alias for it. An install with --features index or --features full still builds, without protoc.

A vector-read build now lists index in yidam --version and the report's features. A client that read index as "this build needs protoc" should read it as "this build can make an index".

An index built before this upgrade is still read. Its corpus.lance/ directory is no longer used. The next index-build removes it.

yidam run plans every epistemic step last

A run that both lands and proposes now proposes at the head it leaves (#1237). Before, a proposal planned between two landings named a head the branch had already passed. The next run found no propose/<head> for the new tip, and proposed again.

What changes for you: nothing to do. Dependencies still run first. A step's report may list in a new order.

The cluster base creates the executor's token secret

yidam/cluster/base now creates yidam-<corpus>-run.service-account-token (#1237). Without it, every pod of a generated workflow waited in Init on a mount that never arrived.

What changes for you: move your base reference to this release's tag. An overlay that copies the base needs the secret too. See cluster-runs.md.

Regenerate a cluster workflow

A workflow from yidam cluster workflow stopped after its first landing (#1237). Its expressions named hyphenated tasks with a dot, which Argo could not resolve. Nothing failed, and the run waited. They now name each task in brackets, as tasks['land-x'].

A run not admitted now ends Succeeded, not in Error. Each task waits for the one before to succeed. A skipped pin used to let the first step start and read an output nothing wrote.

A CronWorkflow now lists its time under spec.schedules. Argo Workflows 4 refuses the old spec.schedule. Argo 3.6, the oldest version the run supports, reads either form.

What changes for you: regenerate every committed workflow. Run yidam cluster workflow again with the flags you used.

cluster status reports what a run did, from records

yidam cluster status lists a corpus's recent cluster runs (#1236). For each run it gives the admission and its reason. Each step is landed, proposed, refused with the lander's reason, or not reached. Each gather peer has its outcome. It reads the records Argo keeps on each Workflow, through kubectl, and never a log. See cluster-runs.md.

A refused landing now writes a record to --out. The record holds refused and the lander's reason, and the pod still fails.

What changes for you: nothing, until you upgrade the image. A lander from an older image writes no refusal record. status shows its refusals as failed, pointing at the pod's message.

A push can submit a cluster run, and every run holds a per-corpus mutex

yidam cluster workflow --on-push github writes an Argo Events EventSource and Sensor (#1235). A push to the branch submits the same run the cron does, and the run asks admit first. The lander's own push submits a run too, and that run finds nothing owed. See cluster-runs.md.

Every generated workflow now holds a mutex, yidam-<corpus>. Two runs of one corpus queue instead of racing. The field is synchronization.mutexes, which needs Argo Workflows 3.6 or later.

What changes for you: regenerate your workflow, on Argo Workflows 3.6 or later. A manifest written before this upgrade still runs, without the mutex. Running on push is opt-in. It needs Argo Events and the streamflow-on-push overlay's two extra objects.

An S3 vault can assume a role by web identity

A vault can use a role from IRSA instead of a stored key (#1234). The default vault assumes AWS_ROLE_ARN with the token in AWS_WEB_IDENTITY_TOKEN_FILE. Another vault names its own with YIDAM_VAULT_<NAME>_ROLE_ARN and …_WEB_IDENTITY_TOKEN_FILE. It never inherits AWS_ROLE_ARN. The remote index reads YIDAM_INDEX_ROLE_ARN the same way. See cli-reference.md and cluster-runs.md.

What changes for you: nothing, unless you opt in. Keys you export for a vault still win over an injected role. A vault given both its own role and its own keys is now refused. doctor now says where each vault's credentials come from.

Fenced clusters need STS. Pods that assume a role call STS first. Add its interface endpoint's addresses to [cluster.egress] sts, then regenerate the policies.

Update the image first. An older binary refuses .yidam/config.toml once it holds [cluster.egress] sts.

The lander can push as a GitHub App

yidam cluster land can push with a short-lived GitHub App token instead of a deploy key (#1233). Set [cluster] git_auth = "github-app" and [cluster.github_app] app_id. Put the App's key in the write secret as private-key.pem. The lander mints a token for the one repository, with contents: write, and pushes over HTTPS. See cluster-runs.md.

What changes for you: nothing, unless you opt in. Deploy keys stay the default. To switch, regenerate your workflow. If you set [cluster.egress] remote, include the GitHub API's addresses too.

Update the image first. An older binary refuses .yidam/config.toml once it holds git_auth or [cluster.github_app].

Cluster pods are labelled by what they may reach, and a new command fences them

yidam cluster workflow labels every pod, and yidam cluster network-policy writes the policies that select them (#1232). Each pod carries yidam.dev/corpus and yidam.dev/egress: remote, vault or internet. A step pod, where a calculator runs, reaches the vault and nothing else. catalog-fetch now runs from its own template, step-catalog-fetch.

What changes for you: regenerate your workflow. Then set the API server's addresses in [cluster.egress] executor and write the policies into your overlay. An s3:// vault also needs vault. See cluster-runs.md. Without a CNI that enforces NetworkPolicy, the policies apply and enforce nothing.

Update the image first. An older binary refuses .yidam/config.toml once it holds [cluster.egress].

Every generated cluster pod is bounded, and every run is cleaned up

yidam cluster workflow now writes resources, a deadline, retries and cleanup (#1231). Each pod requests 250m CPU and 512Mi memory, is limited at 2 CPU and 2Gi, and fails after an hour. pin, survey and step retry twice. land never does. Argo deletes a pod that succeeded, and a workflow a day after it succeeds or a week after it fails.

What changes for you: regenerate your workflow. Set other sizes in [cluster.pod] and [cluster.cleanup]. A calculator can set its own under [capability.<name>.cluster]. See cluster-runs.md.

Update the image first. The pods read .yidam/config.toml and .yidam/capabilities.toml. An older binary refuses either file once it holds one of these tables.

Every generated cluster pod meets the restricted Pod Security Standard

yidam cluster workflow now writes a security context on every template (#1230). Each pod runs as uid 1000, with a read-only root filesystem and no capabilities. It writes only to two emptyDir volumes, /tmp/yidam and /home/yidam, and a file:// vault.

What changes for you: regenerate your workflow. A manifest written before this upgrade still runs. It is refused by a namespace that enforces restricted. See cluster-runs.md.

A cluster corpus deploys with one kubectl apply -k

The objects around a generated workflow are now a Kustomize base and overlay (#1229). The service account, both git secrets and the vault claim come from yidam/cluster/.

What changes for you: docs/cluster/argo-rbac.yml is gone. Its objects live in the base, which your overlay names by URL at your cli/v* tag. Copy the streamflow overlay, set its prefix to your corpus, and add your key files. Then run kubectl apply -k. See cluster-runs.md. Objects you already created keep working, since the names are unchanged.

Each corpus on a cluster names its own secrets and service account

yidam cluster workflow now names every object for its corpus, as yidam-<corpus>-<role> (#1228). Two corpora in one namespace used to share yidam-git-write, so either lander could move the other's refs.

What changes for you: a regenerated workflow refers to new names. Your cluster still holds yidam-run, yidam-git-read, yidam-git-write and yidam-vault. Recreate each under its new name, and apply the Kustomize overlay in cluster-runs.md. Or keep the old names by setting them in [cluster.names]. See configuration.md. Keep old names only when one corpus runs in the namespace.

A gather runs on a cluster, and each peer's answer has a receipt

yidam cluster workflow now adds a gather's tasks for each file in .yidam/gathers/ (#1217). Each peer is asked in its own pod, and nothing but the lander holds a git credential.

What changes for you: a local yidam gather now commits receipts too. They land at .yidam/runs/gather/<name>/<peer>.yml, one per peer that answered or came back empty. A gather branch you already proposed holds none, so a repeat run builds a different tree. Pass --force to replace it, or delete the branch first. A corpus without .yidam/gathers/ gets the same workflow as before.

regen and vault push author their own commits

yidam regen --commit and yidam vault push --commit write the regen:, index: and bundle: commits (#1215). Each commits only the tracked files it changed, under its own author, and commits nothing when nothing changed. It refuses a file that already has uncommitted edits.

The index workflow now runs yidam vault push --index --commit and pushes. Its Commit the lock step is now Push the lock commit. Take the new .github/workflows/index.yml on upgrade. index-build and bundle still commit nothing, because their output is gitignored.

An interval's target may mark its line of holders finished

interval: accepts complete:, naming a property on the exclusive_over target (#1213). Write complete: line_complete on a tenure class, and line_complete: true on each finished office.

The new interval-gap check then warns on a span inside that line held by fewer than it seats. Spans before the first holder and after the last are not gaps. Targets without the mark are unchecked.

A calculator the corpus cannot run yet is declared, not stubbed as a skill

A capability in .yidam/capabilities.toml may omit run (#1184). It parses as declared and not built. Every yidam run plan holding it is refused by name, and nothing lands.

The bootstrap now declares an unrun calculator there instead of writing a skill stub in .yidam/skills/. An existing calculator stub can move the same way. Declare its reads, writes and verb, then delete the skill. Until it gains a run, a bare yidam run refuses the whole manifest.

lint reports a skill that does not say whether it is built

yidam lint now reports skill-status-unstated at Info (#1182). It names each skill in .yidam/skills/ whose status: is missing. It also names a skill whose value is neither built nor stub.

Every skill written before #1063 is reported after this upgrade. Nothing gates on it. Add status: built or status: stub to each one, then run yidam skills-index.

The consumption record names the nodes retrieve returned

A retrieve line in .yidam/record/calls.jsonl now carries node_ids (#1020). It lists the ids retrieve returned, in rank order. Every other tool records null.

yidam record uses them to name the corpus nodes no recorded retrieve returned. Its JSON report gains consumption.reach, which is null over a record written before this change. A line without the key is still read. Nothing needs to change in a corpus.

yidam record --fold commits the consumption record

The record [serve] record keeps can now reach the history (#1018). yidam record --fold counts the new lines of .yidam/record/calls.jsonl into .yidam/consumption.json. It commits that file alone, as one refresh: commit on the current branch. The commit is operational, so no proposal branch and no author are involved.

The file is never truncated. The fold remembers how many bytes it counted, and takes only complete lines. A line a server writes during the fold is counted by the next one. With nothing new to count, the fold writes no commit, so it can run on a clock.

yidam record now reads the committed counts and the file together. Its JSON report gains consumption.folded, which is 0 in a corpus that has never folded. Nothing needs to change in a corpus until you choose to fold.

serve --mcp --http can require a bearer token

Set YIDAM_SERVE_TOKEN or pass --token-file, and every request needs the token (#939). A request without it gets 401 on every path. Nothing changes until one is set.

What changes for you: check the environment you serve from. An empty YIDAM_SERVE_TOKEN now refuses to start. So does setting the variable and --token-file together.

A token does not lift the loopback rule for [serve] act. See mcp-server.md.

A bind off loopback warns at startup

serve --mcp --http --bind with a non-loopback address now prints a warning (#939). The transport authenticates nobody. Anyone who reaches the port can call every read tool. The warning names each served tool, and the two repairs.

What changes for you: nothing, unless you watch stderr. The server still starts and answers. Bind 127.0.0.1, or require a bearer token. A token silences the warning.

Domain libraries are vendored beside the prelude, not inside it

The domain libraries moved from yidam/prelude/domains/ to yidam/domains/ (#934). The prelude copy no longer carries them. yidam-vendor-update copies only the domains named in prelude_domains into .yidam/.vendor/domains/. Without that key, it keeps the domains this repository already vendored.

What changes for you: a vendored domain changes path. The next re-vendor moves it from .yidam/.vendor/prelude/domains/<domain>/ to .yidam/.vendor/domains/<domain>/. Re-point any crates/Cargo.toml path or packages/ dependency that names the old path. A repository that vendors no domain sees no change.

Every vector index needs rebuilding

The embedding runtime moved to fastembed 7, and it embeds into a different vector space (#536). Its ONNX Runtime is newer, and the quantized kernels answer about 3e-4 differently per dimension. The TypeScript SDK moved with it, because transformers.js 4.3 answers the same way.

What changes for you: re-run yidam index-build. Re-run yidam index-push too if you push one. Until then, semantic retrieve reports stale_contract and answers with keyword search instead. It does not rank against vectors from the old space. An index built before the witness existed is not checked. yidam index-verify reports mismatch on an old index, and match once it is rebuilt.

yidam dispatch runs an agent seat as a run

yidam dispatch <question> --seat <name> runs the elector a seat declares in .yidam/sangha/dispatch/<name>.toml (#477). The position lands on a propose/* branch with a receipt of what ran. The seat's registry row must already record that model, version and config hash.

What changes for you: nothing, unless you dispatch a seat. .yidam/sangha/dispatch/ is new and absent by default. yidam lint gains elector-receipt-disagrees, a warning that is silent until a dispatch receipt exists. See cli-reference.md for the declaration's shape.

yidam gather asks pinned peers a question

yidam gather <name> runs the question in .yidam/gathers/<name>.toml against each tonpa peer (#476). Each peer's answers land as cites: on one ? question node, on a propose/* branch.

What changes for you: nothing, unless you write a gather. .yidam/gathers/ is new and absent by default. No existing command changed. See cli-reference.md for the file's shape.

yidam cluster runs the manifest on Argo Workflows

yidam cluster workflow, admit, pin, step, land (#475, RFC-0026 §7). The same run as yidam run, one pod per act. workflow generates the Argo manifest from .yidam/capabilities.toml and [cluster] in .yidam/config.toml. The step pod holds no credential that can move a ref; only the lander does. cluster-runs.md is the deployment guide, for a file:// vault that needs no credentials and for s3://.

What changes for you: nothing, unless you deploy it. [cluster] is a new config table and is absent by default. No existing command changed its behaviour.

Every workflow also runs the catalog. catalog-fetch, catalog-extract and catalog-reconcile run ahead of your manifest's steps. A manifest that declares one of those names has no workflow. Rename the capability.

Receipts are now format_version: 2. A receipt can record version, and image_digest on a cluster. The digest is recorded only for an image pinned by @sha256:. Version 0.17.0 reads these receipts unchanged.

check-diff offers fewer nearest names

A nearest candidate now needs a shared root of five characters, up from four (#390). Across fourteen derived corpora, more than half of the four-character candidates were wrong. Most shared a truncation such as stat, offering status for statement.

What changes for you: fewer candidates, and no findings. Every unmodelled-concept row is still reported. A few right candidates on four-letter words are gone, such as vote.

cli/v0.17.0

An interval's target may seat more than one

interval: accepts capacity:, naming a property on the exclusive_over target (#1205). Write capacity: seats on a tenure class. Then an office with seats: 3 may have three holders at once. A target that omits the property holds one. Quoted digits such as "3" count. A value that is not a whole number of at least one is reported on the target.

interval-overlap now reports each holder once, naming every earlier holder it overlaps. It used to report once for each overlapping pair.

A class may declare its interval

interval: names an instance's start and end (#1201). Write start: and end:, each a date property the class declares. Add exclusive_over: with a relationship from edges:. No two instances may then link one target by it at once.

A new interval-overlap lint check is an error for each overlapping pair, and for an end before its start. Intervals are half-open. They compare as query orders dates, at the precision both sides share. So 1893 and 1893-06-01 meet rather than overlap. An absent end is still open.

Nothing changes until a class declares interval:. A declaration with a misspelled key, or no end:, is a malformed class.

A new version of a source names the nodes that read the old one

yidam catalog-fetch names every node citing an entry when it records a new version (#1200). A new version is a digest from a location the entry already held a digest from. The report and the refresh: commit both list the nodes. The JSON row gains a superseded list.

yidam due gains a fifth clock, superseded. It lists each node citing a source that has changed since the node was last committed. Set [due] superseded_after in days to let it come due. A commit touching the node discharges it. A new text reading of a PDF is not a new version.

Nothing needs changing. The clock reads undeclared until the key is set, and still reports what it measured.

An editor rename between classes now re-relativizes the moved node's links (#1193). Before, F2 moved the file and rewrote inbound links. It dropped every edit to the moved node itself. A link written as ./sibling.yml was left pointing into the wrong class. yidam rename was not affected.

What to do. Run yidam lint after any cross-class F2 rename made before this release. graph-check reports each link it left dangling.

A class rename keeps its instances' ages

yidam migrate class writes moved-from: into every instance it moves (#1192). Before, a class rename restarted both commit counts for each instance. Every orphan's escalation clock reset. Every open question dropped off due's overdue list.

The line is the one yidam rename writes, for example moved-from: ../gage/canyon-outlet.yml. An instance that already declared one has it replaced. The migrate plan lists each line it adds. The JSON report gains a moved_from list. Class renames made before this release are not backfilled.

A renamed node keeps its ages

yidam rename writes moved-from: into the node it moves (#1180). Before, a rename restarted two counts of commits. One is how long nothing has cited a node, which orphan-in escalates on. The other is how long a question has stood [open], which due reads. A renamed overdue question dropped out of due entirely, and its clock read Ok.

The new line names the old path the way a target: does, for example moved-from: ../concept/low-flow.yml. Both counts now carry across the move. A move that also adds a citation or answers the question still ends that count. F2 in an editor writes the same line. A second rename replaces it.

A move made without the command still restarts both counts. To keep them, add the line by hand in the commit that moves the file. Moves made before this release are not backfilled. The rename JSON report gains a moved_from object.

A quotation of a PDF is checked against a text reading

New command, yidam catalog-extract (#1172). It takes a text reading of each PDF artifact. It files the reading in the vault cache and records it under the PDF as text:. It commits the change as extract:.

Lint compares a quotation of a PDF with that reading. Before, every such quotation was quotation-unchecked. Now a span missing from the reading is quotation-span-drift, an error. Run catalog-extract on the machine that holds the PDFs, then run yidam lint.

Nothing changes until you run it. A PDF with no reading stays quotation-unchecked. An older binary ignores the text: key.

yidam rename moves a catalog entry

yidam rename catalog/old new renames a catalog entry (#1159). Before, the command took corpus nodes only. Renaming an entry by hand left every edge source: naming its old stem, which edge-source-unresolved then reported.

The command now moves .yidam/catalog/old.md to new.md and rewrites every citation of it. An edge source: is rewritten in the spelling its author used, stem or path. A markdown link under .yidam/ that resolved to the entry is re-relativized from the file that holds it. That covers node prose, other entries, decision records and the catalog README. On the largest corpus we measured, one rename rewrote 107 citations across 41 files. Lint was identical before and after.

Anything that names the old file without linking it is reported and not rewritten. The report's corpus_dir is .yidam for a catalog entry, and from and to read catalog/<name>.md. --dry-run prints the plan and changes nothing. Nothing changes for a corpus node rename.

An edge source: counts as a citation

catalog-uncited and verified-unsourced read edge sources (#1158). Before, only a links: target or a prose link to a catalog entry counted as a citation. An entry cited only from edge source: values was reported uncited. A node whose [verified] claim rested on such an edge was reported unsourced. Yet edge-source-unresolved resolved every one of those edges.

Now the resolver every citation count shares reads edge sources too. It admits the same two catalog spellings: the entry's file stem, or a path written as a target: is. catalog audit and the MCP claim surface read the same function, so their counts move with the gate's.

Two checks may change on upgrade. catalog-used-by-drift compares an entry's hand-written used-by list to the nodes citing it. More citations can mean more drift. On the largest corpus we measured it rose from 79 to 86 findings, all Warn. catalog-unobtained-but-cited is Error and now fires for an edge resting on an obtained: false entry. No corpus we measured had one.

The graph report says what omitting a property costs

A new field, omission, on each class property in yidam graph --format json (#1155). Its value is gates, reported or licensed: the verdict missing-property gives when an instance omits the property. Before, the report carried only required, one bool. A property marked required: false and one that said nothing both arrived as false. The web editor labelled a licensed omission reported.

required is unchanged. The web editor reads omission and labels a licensed property allowed. Against a binary older than the field, it labels a false property does not gate rather than guessing. Nothing changes for a corpus.

doctor asks whether the ontology ever stated its contract

A new contract check (#1078). It warns when no property in the ontology says required:. It also warns when no class with edges says edge_policy:. Either way, missing-property or unlicensed-edge can warn there and never gate.

Writing the key is the answer, whatever its value. required: false counts, and so does edge_policy: characteristic. One class answering answers for the whole ontology.

It is a warn, so doctor still exits 0. doctor --strict does not. Of 16 derived ontologies measured, 14 warn.

doctor --only <id> reports only the named checks. yidam-vendor-update runs doctor --only contract after it re-vendors. A binary that predates the flag prints nothing there, so the first re-vendor after an upgrade may stay quiet.

Lint warns on a node linked only to its class

only-instance-of is a new warning (#1072). It reports a node whose only link is to its own .ont.yml. The finding names the relationships its class declares. Add one of them to the node, or delete the node if it is a stub.

A class the ontology names only as an edge's target is a leaf by design. Its instances are exempt. The warning never fails the gate.

A quotation property type

A property may be declared type: quotation (#1070, RFC-0046). Its value names a catalog entry in of: and holds the copied words in span:. Add sha256: when the entry holds more than one artifact. quotation-span-drift fails when the entry's cached bytes lack the words. quotation-unresolved fails when of: or the pin names nothing. Where the bytes are not in this machine's vault cache, or are not text, quotation-unchecked reports it at Info. A CI runner with no cache sees only Info findings.

Nothing changes until a class declares the type. A corpus that coined quotation for itself is now checked against this shape. yidam rename rewrites of: with the entry.

A quotation's of: is a citation of its entry (#1174). catalog-uncited and verified-unsourced count it, as they count an edge source:.

Lint reports a decision or a URL nothing registers

New Info finding, decision-uncited (#1068). It reports a decision record nothing in the repository refers to. A markdown link to the record counts. So does its path, decisions/<stem>, named in any file git tracks, code included. A links: target or an edge source: naming its id: counts. So does a decision/<id> entry in references:, or another record's supersedes:. Text inside a REGEN block, or in a vendored or generated region, does not count. Across 13 derived corpora, it reported 29 of 346 records. Info, not a gate: your exit code does not change.

New Info finding, source-unregistered (#1068). It reports a URL in a node or a catalog body that no catalog location: covers. A location covers its own path and every path beneath it on that host. A corpus that declares no url or url_template location is not read. To clear a finding, register the source, or add the URL as a location: on its entry. Info, not a gate: your exit code does not change.

An edge source: is resolved

A new Error check, edge-source-unresolved (#1067). Before, lint checked only that a verified edge wrote a source:. A value naming a renamed or nonexistent catalog entry passed.

Lint now resolves the value on every edge that writes one, whatever its tag. Three spellings resolve: a catalog entry's file stem, a path written the way target: is, or a decision record's id:. Every edge source in every derived corpus we measured already resolves. A corpus that writes none has nothing to do.

If the check fires, the finding names the edge and the value as written. Rename the value to the entry's current stem, or baseline the finding.

The scaffolded .gitignore ignores .vscode/settings.json

The yidam extension writes this file itself (#1065). At activation its vendor guard marks .yidam/.vendor/** read-only. Its schema wiring adds the yidam schema --settings mapping. Both land in .vscode/settings.json. A git add -A then commits the file. Three derived repositories did.

Why that matters. Other extensions write machine paths into the same file, such as a Python interpreter under your home directory. A tracked copy publishes the next one.

What to do. A new repository gets the rule at genesis. It matches at any depth. An existing repository can copy it from sadhana/root/gitignore. If the file is already committed, git rm --cached .vscode/settings.json untracks it. The extension re-applies the guard in every window, so no protection is lost. To keep sharing the file on purpose, add !.vscode/settings.json after the rule.

skills-index reports whether a skill is built

A skill's frontmatter may say status: built or status: stub (#1063). yidam skills-index adds a Status column and a count line above the table. A skill that says neither is reported as unstated, never as built. The bootstrap now writes status: stub into each calculator stub it leaves.

After this upgrade, yidam regen --check reports .yidam/skills/README.md as stale. Run yidam skills-index and commit the table. Every existing skill reads unstated until you add the field. Nothing gates on the value.

A built skill that another derivation also wrote can now be sent upstream. upstream.md names the from:derived-skill label and its template.

yidam schema leaves a schema file it did not write alone

Repo-owned schemas (#1057). Every file yidam schema writes now carries a marker in its $comment. When a target in .yidam/schemas/ has no marker, the run refuses before writing anything, and names the files. A repository that compiles its own, stricter schemas into that directory keeps them. It needs no guard task around mise run schema any more.

Files an earlier release wrote have no marker either. The first run after this upgrade refuses them. Replace them once, and commit the result:

yidam schema --force

yidam schema --settings is unchanged. It reads no schema file and writes none.

required: false silences missing-property

An omission the class licensed is no longer a warning (#1055). Before, missing-property warned on every omitted property that was not required: true. A property marked required: false warned the same as one that said nothing.

It is now silent on required: false. A property that says nothing still warns, and required: true still gates. To accept a standing missing-property floor, write required: false on the properties an instance may omit. No baseline is needed.

A re-vendor names the workarounds it makes unnecessary

Cited issues (#1054). Record a workaround with the upstream issue it works around, as yidam#587 or as the issue's URL. After a re-vendor, yidam-vendor-update lists each cited issue that a commit at the new pin fixes. The workaround for it can go. git grep yidam#587 finds it.

It reads tracked files only, and skips .yidam/.vendor/ and .yidam/corpus/. It needs no network beyond the clone the re-vendor already makes.

A re-vendor now reaches ci.yml and CLAUDE.md

Scaffold regions (#1054). Genesis installs .github/workflows/ci.yml and .claude/CLAUDE.md once. Until now no re-vendor touched them again. So a gate added upstream never reached your CI.

The scaffold now marks the part of each file that is yidam's. In ci.yml that is the privacy and corpus jobs, between # <!-- YIDAM:CI --> and # <!-- /YIDAM:CI -->. In CLAUDE.md it is the template's sections, between <!-- YIDAM:CLAUDE --> and <!-- /YIDAM:CLAUDE -->. mise run yidam-vendor-update rewrites each region from the scaffold at the new pin. It never reads the rest of the file.

An existing repository has no markers. Install them once, then re-vendor:

yidam migrate --dry-run scaffold   # see what each region takes in
yidam migrate scaffold             # do it
mise run yidam-vendor-update       # fill the regions

Commit the migration as a migrate: commit. Anything inside a region is replaced. A step you added to the privacy or corpus job shows in the re-vendor's diff as removed. Move it to a job of your own, outside the markers.

A workflow with neither job gets an empty region, and the re-vendor fills it. A CLAUDE.md with none of the template's headings is yours, and is left unmarked. The migration refuses when one of your sections sits between two of the template's. Move it, then run it again.

yidam doctor has two new checks. scaffold warns while a file has no region. ci warns when no workflow runs a corpus gate. It reads .github/workflows/ only, and follows a mise run into your own mise.toml.

A node may declare a refusal, and derive check holds an argument to it

refuses: is a named node field (#1053, RFC-0045). It lists the sentences in which a node declines an inference. A new refusal-span-drift lint check is an error when one quotes text the node's prose no longer holds. A corpus that declares no refusals sees nothing new.

yidam derive check reads artifacts under [derive] paths. Without that key, it reads nothing and passes. With it, every memo or dossier there needs a reach: and cites: spans. It must also answer each declared refusal in a paragraph it cites.

SDK parity moves 0.16.0 → 0.17.0 and yidam-core 0.10.0 → 0.11.0, for the new field. An SDK that predates it keeps refuses: in extra, where nothing reads it.

export --format llms prints instead of writing llms.txt

Stdout by default (#919). Without --out, yidam export --format llms wrote llms.txt at the repository root. A reader who only meant to look at the corpus got an untracked file.

It now prints the pack to stdout. The summary line goes to stderr. With --out, nothing changes. A script that reads llms.txt after the export needs --out llms.txt.

A domain article is checked, as the genesis commit holds it

Four new checks read .yidam/constitution/ (#593, RFC-0047). Bootstrap now writes a constitutional augmentation there, with its Rego rule and cases. yidam lint reads each rule from the genesis commit. domain-article-violated fails on a rule's refusal. domain-article-edited fails when a file there differs from the genesis commit. domain-article-unproven warns on a rule with no cases, or a failing case. domain-article-unverifiable warns in a shallow clone, where no rule is read.

Nothing changes without the directory. No derived repository has one yet. An article appended to the vendored CONSTITUTION.md did not survive yidam-vendor-update, and none was found.

A resolution record must name its rounds and positions

New check, resolution-deliberation-unrecorded (#592). It names a resolution record missing rounds: or positions:. It also names a rounds: that is not a count of at least one. PROTOCOL.md has asked for both fields since 2026-08-20. No record in any derived repository carries them.

Old records warn. New ones gate. Git ancestry decides which is which. A record gates when the commit that added it descends from the commit that put rounds: into your PROTOCOL.md. A repository bootstrapped after 2026-08-20 has that line from genesis, so every record it adds gates. A repository whose vendored PROTOCOL.md lacks the line only warns, until it re-vendors.

The repair is two lines of frontmatter. Write rounds: 1 if the loop ran once. List every position file the loop read under positions:. A shallow clone cannot see the ancestry, so there every finding warns.

cli/v0.16.0

A multi-line value leaves an inline block that shares its line

The marker contract (#1137). update_regen wrote a value that holds a newline in block form. Block form is read by line. The open tag must start its line, and the close tag must stand alone on its own. An inline block inside a sentence has neither, and the rewrite broke it two ways. With text before the open tag, the tag became prose and the block was never read again. With text after the close tag, the next run read on to a later block's close tag. It then wrote over that block too.

Such a block is now left as it is. An inline block with its line to itself still takes the block form. SDK parity moves 0.15.0 → 0.16.0.

What changes for you: nothing, unless a generator returned more than one line into a block inside a sentence. No generator does today. count returns one number. If one does, yidam regen leaves that block unchanged and regen --check does not report it. Move the block onto a line of its own.

AGENTS.md reads by occasion, and a new generator writes it

yidam routes (#972, RFC-0039). A new derivation's AGENTS.md no longer lists every prelude file to read before acting. It carries a <!-- REGEN: yidam routes --> block instead: what every occasion reads, then one heading per occasion, each a list of section links. An occasion is named by the commit verb it ends in. The block is rendered from .yidam/.vendor/prelude/routes.yml, so a re-vendor brings the new routes and regen --check reports a stale block.

An existing derivation's AGENTS.md has no markers, and a generator writes nothing where it finds none. So yidam regen leaves the file as it is, and the whole-file list keeps working.

yidam migrate routes puts the routes block into an existing AGENTS.md

yidam migrate routes (#1135). Re-vendor first, so the prelude carries routes.yml. Then:

yidam migrate --dry-run routes   # see which list it replaces
yidam migrate routes             # do it

It replaces the bullet list under Before taking substantive action with the rendered block. No other line of the file changes. Commit the result as a migrate: commit. From then on, yidam regen keeps the block current, and a stale one fails regen --check.

It refuses when the heading is missing or has no list under it. So does a bullet in that list linking anything but a vendored prelude file. That line is yours. Each refusal prints the block to paste by hand. yidam doctor warns under routes until the block is there.

The skills README no longer explains where judge went

sadhana/skills/README.md (#1077). The scaffold's skills README ended with a paragraph about judge. It said the skill used to be listed there, and why it left. That is a note about the template, and every repository installed it at genesis. A reader there has never met judge.

judge scores runs of yidam's own bootstrap test harness. It lived in prelude/skills/, so every derived repository vendored it. The bootstrap skill also read it before starting work. In cli/v0.2.0 it moved to yidam/tests/, beside the harness that calls it. A derived repository has no copy of that harness.

What changes for you: nothing. New repositories get the table only. In an existing repository, the paragraph under "Inherited from prelude" in .yidam/skills/README.md can be deleted.

A scaffold for watching a source, where unreachable is not unchanged

sadhana/github/workflows/watch.yml (#1073). A derived repository polled a source on a schedule. For 24 rounds the source was unreachable. The job saw no diff, so the build stayed green.

The new workflow runs a round you write at .github/watch/round. It appends one row per round to .github/watch/heartbeats.tsv, and commits nothing else. A round that crashes, or prints no verdict, is filed unreachable. A watch job in ci.yml reads the ledger. It fails after seven unreachable rounds in a row, or seven days with no round.

What changes for you: nothing until you arm it. The workflow ships with no schedule. The gate runs only when the ledger exists. An existing repository can copy both workflow changes from sadhana/github/workflows/. The header of watch.yml says how to arm it.

broken-object-link (#577, RFC-0028 Erratum 6). A repository declaring [object] paths holds a corpus and an artifact that cite each other. A node's link into the artifact was already checked. A link from a crate README to a node was read by nothing. Deleting the node left it dead, and no finding named the README.

What changes for you: new warnings, if you declare an object. yidam lint now reads the tracked .md, .rs and .ts files [object] paths claims. Each relative link into .yidam/ must resolve. A dead one is a warning at the line that holds it. Warnings do not fail the build, and escalate_after cannot raise these. Fix the link, or drop it if the node is gone on purpose. A #L range on such a link is now held by the line-citation checks too. A repository without [object] paths sees nothing new.

kuten check gains a coupling field. It counts the links each way. For nodes, decisions and catalog entries, it says how many the artifact cites and how many cite it. It is null without an object, and for a projected corpus. The field is not required in the report schema, so output from an older CLI still validates.

A derived repository overrides inherited tasks from mise.overrides.toml

The scaffold ships an include slot for overriding inherited tasks (#1064). A task in mise.toml cannot override one from mise.yidam.toml. In mise, an included task wins over the file that includes it. Among includes, the later one wins. A repository that needed to replace an inherited task had to invent a second include. It also had to learn that rule. New repositories now get mise.overrides.toml at genesis, empty and listed last. No vendor update writes it.

What changes for you: nothing, unless you want the slot. An existing repository keeps its mise.toml, which the vendor update does not rewrite. To adopt it, list the file after the inherited layer:

[task_config]
includes = ["mise.yidam.toml", "mise.overrides.toml"]

A missing include is skipped without a word, so the line is safe before the file exists. A repository that already keeps its own override include can keep it, or rename it. Do not use mise.local.toml: mise also loads that name as a config file and warns about every task in it.

migrate value renames one value of a closed set

A value of a declared values: set can be renamed as one event (#1120). Declaring a set closes it. So creek → stream could not be done in two steps. Renaming the declaration first puts every instance in violation. Renaming the instances first puts them outside the set. yidam migrate value <class> <property> <from> <to> does both halves together. It rewrites the item on the declaration and the value on every instance holding it. It writes a migration record. Quoting follows what was written. A value outside the set is refused. So is a rename onto a value already in the set.

A class declares a closed value set, and property-type holds instances to it

values: on a string property (#1052, RFC-0044). A class could not declare the set of values a property admits. So 40 properties across seven corpora spelled one in the description, as extant | demolished | ruin. Nothing read it there. 33 instances held a value outside the set their own class documented. A string property now declares the set as values: [extant, demolished, ruin] beside type:. Declaring it closes it.

What changes for you: nothing until a class declares a set. No corpus carries values:, and a property without one is unbounded, as before. Once a class declares the set, property-type reports every instance holding a value outside it and names the set. The finding gates, as the check always has. Each report is one of two things. A value the set should have carried is one line on the declaration. Prose in a token field is a value to restore. The match is exact: In operation is not in operation. The compiled class schema now carries the set as enum, and the gate is no looser than the schema.

migrate retype into string is held to the set. A set on any other type is carried and ignored, so it starts to bind at the retype. An instance outside it is reported and blocks before anything is written.

A class file carrying values: is refused by every earlier CLI. The class-file schema is closed. An older CLI would compile the set to nothing and validate the drift as fine. Upgrade before adopting the field. SDK parity moves 0.14.0 → 0.15.0 and yidam-core 0.9.0 → 0.10.0. Both are for the new OntologyProperty.values field, which every compiler emits.

phase settle refreshes the REGEN blocks, and a gates generator writes the gate table

yidam phase settle (#1066). Closing a phase requires the REGEN blocks to be current, and settle never touched them. Every repository ran regen by hand one commit before the phase commit. In the reporting corpus that was 101 of 118 phase commits. settle now asks what regen --check asks, refreshes what is stale, stages it, and asks again. The printed sequence opens with the regen: commit when there is one to write.

What changes for you: a phase with a stale block is not ready. settle used to say ready over a block CI would have called stale. It now says not ready, with the remedy. A block no generator writes is not ready either. Nothing is refreshed from a checkout that differs from HEAD. settle names the files and the sync instead. A block generated from that tree would not hold against the commit. The report carries a regen object: what passed, what is stale, what was staged, and what was dirty.

yidam gates (#1066). A new generator, run by yidam regen with the others. It writes a table of every run: step in .github/workflows/ci.yml into the README's yidam gates block. The scaffold's README carries the block in place of the sentence that named three gates by hand. An existing repository adds the block where that sentence is, and runs regen.

A declared gluon calculator is now refused by yidam lint

yidam lint (#1099). A capability declaring run = { gluon = "..." } was only checked when it ran. A script at a path that does not exist, or one invoking a macro, was quiet until the step. lint now refuses all three failures from the manifest, without invoking a calculator.

The three are reported as separate checks. calculator-script covers a path that does not read and a script invoking a macro. calculator-scope covers a name the closed prelude does not bind. calculator-type covers a script that is not Corpus -> Computed.

What changes for you: a corpus with a broken calculator now fails lint where it passed. The repair is the one the step would have demanded anyway. Nothing here is a new rule about what a calculator may say — lint and run call one admission function.

calculator-scope and calculator-type need a typechecker. They are absent from the report of a binary built without calculators-gluon, which is the one install.sh downloads. A build that held no script to the prelude should not report that it did. calculator-script is text, so it gates in every build.

Bless either of the two from a full build and lint from a light one. The entry is carried (#1114). The light run did not ask the check, so it neither compares the entry nor reports it stale. It prints the ids it did not ask. A blessing from the light build keeps the entry too. The same holds for unrecognized-verb without --commits. An entry under a check no build has any more is still stale, and still fails.

A re-fetched artifact record keeps the redistributable: the entry already carried

yidam catalog-fetch (#1074). A record's vault: and redistributable: are decisions a person makes. A fetch left both blank on every record it wrote. That is right for a first capture: nothing an HTTP 200 establishes is a licence. It was wrong for a re-capture. A source you had cleared produced a new record silent on the question. vault push then refused the new bytes, and one licensing decision had to be re-entered by hand per edition.

Both fields are now carried forward from the entry's latest record for that same location. The refresh: commit body names each field it carried and the digest it came from. A licence on a new record is reviewable as continued rather than established.

What changes for you: a re-capture may now arrive already cleared. The assertion is still yours. The command reproduces the record you wrote and never invents one. A first capture is unchanged and still records neither field. Only the latest record for a location is consulted. Change your answer and every edition after it inherits the new one.

Entries whose latest record the old command wrote need one edit. That record is silent, and a silent record carries nothing forward. Nothing here can tell a silence you intended from one the command left, so it does not guess. Put redistributable: on the newest record for that location once, and vault: if you had one. It carries from there. A record with no from: names no location and is never a source for a carry. Those are written by hand or by a bulk importer.

A REGEN block written on one line stays on one line

The marker contract (#1094, RFC-0043). update_regen wrote every block the same way. A newline after the open tag, the content, a newline before the close tag. A block written inside a sentence came back as four lines, the sentence broken across them. That is the shape RFC-0043's count generator needs, and the reason no generator writes one today. A block whose body holds no newline is now written back without newlines. It stays where its author put it.

What changes for you: nothing, unless you had already written one. No generator emits an inline block today, so no existing document changes shape. If you hand-wrote one and watched yidam regen unwrap it, it will now survive. A value holding a newline of its own still goes back in block form. It cannot fit on the line. A body that did not match its form would be rewritten on the next run.

update_regen finds the block scan_markers sees

The marker contract (#1094). The two halves of the contract located a block differently. scan_markers required the open tag to begin its line. update_regen searched the bytes and took the first prefix match. Three consequences, all silent:

  • A block in the middle of a line was invisible to the reader and rewritten by the writer.
  • A block at column 0 whose close tag sat alone on a line swallowed the next block too.
  • update_regen matched a command that merely began with the one asked for.

There is now one locator. update_regen asks scan_markers for every block. It updates each one whose command is equal to the one requested — every one, not the first.

What changes for you: a document with two blocks for the same generator now updates both. That was the intent all along. The old behaviour updated the first and left the rest stale. regen --check then reported drift the command could not clear. A command that is a prefix of another generator's name no longer matches it.

A capability may declare a typed calculator

.yidam/capabilities.toml (#1091, RFC-0042). run takes a second shape. A table naming one gluon script sits beside the sequence it has always taken:

run = { gluon = ".yidam/capabilities/travel-tier.glu", calls = 2000000 }

The script's entry point is declared Corpus -> Computed. It is applied in this process. So a typed calculator gets no scratch tree, no child process, and none of the five environment variables.

What changes for you: nothing, unless you write the new form. Every existing run = ["sh", …] parses and runs as before. A receipt already committed for one keeps its bytes.

Two things are worth knowing before you write the table form. A typed calculator must declare its own .glu under reads, the same rule the shell arm has. A declaration that does not is refused by name. The script's digest goes in the receipt and in the input state, so editing a calculator makes its step stale.

The arm is also behind --features calculators-gluon, which is outside the default set. The binary install.sh downloads parses the declaration and plans it. It then declines that step by name, and says which feature would run it. A corpus that wants the downloaded binary to run it writes the sequence form.

regen --check reports a block no generator writes

yidam regen --check (#1062). A REGEN block whose command names no generator used to be skipped in silence. Nothing wrote it, nothing reported it, and the gate passed. It now fails, naming the file and the command.

What changes for you: a repository that passed may now go red. The cause is a marker whose name is wrong, usually a typo. The block has been stale since it was written. Correct the name, or delete the block. yidam regen does not clear it, because no generator carries that name.

Only commands beginning yidam are judged, so a block your own tooling refreshes is untouched. Measured across twenty-two repositories carrying REGEN blocks, the check found none, so most upgrades will see no change.

yidam count — a number in prose, checked against the graph

New command and new REGEN generator (#1071, RFC-0043). yidam count <query> prints how many nodes a query matches. With no query it is the generator yidam regen runs: it refreshes every <!-- REGEN: yidam count <query> --> block in the tracked markdown set. Inline, so the number sits inside its sentence. A figure published in prose is now checked by yidam regen --check instead of remembered.

What changes for you: nothing until you write a block. No existing document has one. To adopt it, replace a hand-counted figure with a block and run yidam regen:

The map has <!-- REGEN: yidam count district -->44<!-- /REGEN --> districts.

Two things are worth knowing before you do.

A query that does not typecheck refuses its block and fails the run. It does not write a 0. A query that cannot run has not counted zero of anything. The block keeps what it holds, and the error names the file, the query and the diagnostic. Under --format json the run emits no report at all, so read the exit code.

A block naming no query — <!-- REGEN: yidam count --> — is reported as unclaimed, not written. No run can fill it. That verdict's wording changed with this release. It used to say the command named a generator that does not exist. It now says the command is one no generator writes, which is the true statement for this block.

migrate retype requotes an instance instead of refusing it

yidam migrate retype (#1044). Retyping to number now unquotes an instance holding "24". Retyping to string or date quotes a bare 24. Both are repairs property-type already named, carried out on the instances and nowhere else.

What changes for you: the command writes where it used to refuse. A retype across the quoting boundary used to exit nonzero. It now edits each instance value, and the corpus still passes its own gate. A value with no number in it still refuses, and names what it tried. about 24 and ~24 are unchanged.

malformed-yaml reads your catalog and your decisions

yidam lint now gates on a catalog entry or a decision record whose YAML does not parse (#1056). The check covered instances and classes. The other two records read through unwrap_or_default(), which turns a file nobody can read into a record declaring nothing. One corpus lost a catalog entry's TTL for its whole history, and a decision record that governed a phase. One unclosed quote each.

What changes for you: a lint run that passed may now fail. Nothing about your corpus changed. What changed is that the silence ended, and the file the finding names was never being read. The repair is the parse error the finding quotes; it carries the parser's own line and column.

Two states are worth knowing before you look.

A catalog entry whose frontmatter did not parse was read as obtained: true. obtained: was absent from the empty record, and absent means obtained. It carried no TTL, no used-by and no artifacts, so catalog-expired, catalog-used-by-drift and catalog-artifact-malformed each passed with nothing to check.

A decision record that did not parse was read as a record with no id: and no summary:. yidam decisions renders that under the file's stem, with an em dash. It is how the log renders a record nobody has filled in.

A file with no frontmatter, and a file with nothing in it, are both unchanged. Neither has contradicted anything, and neither is reported. A frontmatter block that opens with --- and never closes is reported: an opened header claims a document follows.

Every other finding about an unreadable file is suppressed, as it has been for instances and classes since #676. Fix the parse error and they come back, correct this time.

retrieve takes a where, and the index carries the properties it reads

yidam retrieve --where '<predicate>' (#1029, RFC-0041). The text inside a query step's [...], verbatim: --where 'began<=1893,ended>?1893'. Same grammar, same check, same comparison, applied before the k cut. It returns the rows query would, ranked. The MCP retrieve tool takes the same string as where. A predicate that cannot be asked is rejected with query's code. An empty answer the predicate caused is predicate-unsatisfied.

What changes for you: re-embed and re-index. The index gains a properties column holding each row's declared date and number values. An index built before this reads as it did, and retrieve without a where is unchanged over it. A where against it is refused as where-unindexed. The repair is the two commands you already run:

yidam embed && yidam index-build

The same re-index repairs #1047. Every corpus.arrow before this held the first ten rows of its corpus, whatever meta.json said. The export read them back through a query with lancedb's default limit. retrieve on a local index and the web shell read that file. A class-unindexed answer over a class the corpus holds was this.

The embedding record gains a properties object, absent where a node has no ordered property. A corpus without one writes the records it wrote before. The SQLite export gains a properties column. meta.json lists the index's columns.

A remote index does not carry the column. index-push leaves it behind on purpose, and a server backed by one refuses a where as where-remote. Keyword search answers one in every build.

MCP contract 0.25.0 → 0.26.0. retrieve gains an optional where. A client built against 0.25.0 never sends one and sees the response it saw.

A property can be a number, and a number can be ordered

type: number exists (#1030, RFC-0040). Declare it on a class property, and write the values unquoted: length_km: 24. A quoted "24" is text, and property-type now says so. The four ordering operators are licensed on it, and = compares numerically. So reach[length_km>9] returns the reach measuring 10, and length_km=7.0 matches a stored 7.

A unit is declared once, on the column. unit: km sits beside type: number on the declaration. Instances carry bare numbers, and the compiled class schema publishes the unit as x-yidam-unit, an annotation nothing validates against. A class file carrying unit: is refused by every earlier CLI's class-file schema, which is the correct refusal.

MCP contract 0.24.0 → 0.25.0. SDK parity 0.12.0 → 0.13.0. yidam-core 0.7.0 → 0.8.0. unordered-property's message names date and number; the code is unchanged. OntologyProperty gains unit in all three SDKs. In Rust that is a new public field on a struct a caller can write as a literal. The crate moves a minor version for it. A client built against 0.24.0 never asks to order a number, so nothing it does today behaves differently. Nothing on disk changes: no corpus has a number yet. examples/streamflow retypes reach.length_km and its two instances drop their tildes.

doctor --strict now asks about .yidam/computed/

doctor gained a computed question (#1028). A calculator's writes glob governed the executor and nothing else. So a corpus could compute an answer, commit it, and have no surface that read it back. doctor now reads what is in .yidam/computed/. It attributes each file to the capability that declares it, and says whether the answer still stands.

What changes for you, and only if you have that directory. A computed file is now a warn when its inputs have moved since its receipt. So is one whose bytes are not the ones the receipt recorded. Both were silent before. doctor still passes on a warning; doctor --strict does not. So strict CI that was green yesterday can go red today, with no file changed. The repair is the one the check prints: yidam run, then commit what it lands.

The window right after a run reads differently from a stale answer. yidam run writes a commit and deliberately leaves your working tree alone. Between the run and the sync, the files it produced are at HEAD and not in your checkout. That is its own warning, remedied by git restore --source=HEAD --worktree --staged -- .yidam/, rather than a report of never having run.

A file that is not a signal table is not a problem. Reading requires a top-level format_version: 1 and a signals: list. Anything else is listed and ignored. cli-reference has the shape, and RFC-0026 §4.2 the argument.

yidam embed attaches computed signals

An embedding record now carries a signals object (#1028) where a signal table names that node. The key is absent where there is none. So a corpus that computes nothing writes the records it wrote before, byte for byte. An index already built stays valid.

What changes for you. If you have signal tables, re-run yidam embed and yidam index-build to pick the signals up. Nothing forces this. The records you have are still readable, and a stale one carries no signals rather than wrong ones. Signals are not part of the embedded text, so the vectors do not move.

The keyword arm can rank

retrieve without a vector index now ranks by BM25 (#1026). It scored the fraction of query terms a node held. Every node holding all of them scored exactly 1.0. The tie broke on the node id. So a two-term query over forty matching nodes returned the first k alphabetically.

This is the only retrieval a released binary performs. --features vector-read is not in the release matrix. So the shipped channel degrades to keyword search, and that arm could not order its answers.

What changes for you. The same nodes come back. Only the order is new. A short node about your query now outranks a long one that merely mentions it. A rare term outweighs a common one.

A degraded score is no longer a fraction of one. BM25 is unbounded. Across the walkthrough corpora in this repository the anchor score now lands between 3 and 6. Every one of them used to read exactly 1.00. Nothing dropped out: the IDF is the +1 variant, which stays positive even for a term every node holds.

An anchored query ranks the same way, over the step's candidate classes. retrieve also reaches installed dependencies, so the same term can weigh differently in the two arms. That follows from the candidate sets, which differ on purpose.

yidam serve --mcp can say whether a corpus has ever been read

serve --mcp wrote nothing at all before this (#719). Not a log, not a counter, not a cache. Thirteen tools dispatched, returned, and the process forgot. So this repository could say who asserted every node, and when, and under what review. It could not say whether any node had ever been read.

One key turns the other side on, in the corpus's own .yidam/config.toml:

[serve]
record = true

With it, one line goes to .yidam/record/calls.jsonl per tools/call, over either transport:

{"at":1758758400,"commit":"2bb499a","tool":"retrieve",
 "args_digest":"sha256:9f3a…","outcome":"ok","results":3,
 "degraded":true,"rejected":false,"ms":12}

That makes four questions answerable that were not. Which queries came back empty — previously discarded, and the most direct evidence of what a corpus is missing. Whether the degraded keyword path served real traffic. retrieve always reported degraded per call, and nothing aggregated it. So this corpus has answered from keyword search for a month was not a statement anyone could make. Whether anything ever acted on a clock. And how much of the read surface is used at all.

Nothing changes for a corpus that does not write the key, which is every corpus today. Absent, the server writes nothing, exactly as before.

Your query text is never recorded. A digest of the arguments and nothing else, on both transports. Over --http a server answers callers it cannot authenticate. The record must not become a file of their questions. The digest is stable, so the same call digests alike.

.yidam/record/ must be gitignored. A server that declared record refuses to start until it is. A derived repository gets the entry from the template's own .gitignore. A repository that has diverged needs the line added. The check asks git check-ignore, so .git/info/exclude or a global ignore file satisfies it too. The rule is vault materialize's. The reason is related: this project's protocols prescribe git add -A, and a tracked record dirties the tree after every served session.

The file is a staging buffer, not the record of last resort. The history is the graph, and folding this into a refresh:-class commit is a scheduled run. git commit-tree on the read path would make the cheapest tool call the most expensive thing the server does. A record of what was retrieved is operational under RFC-0026. So it needs no new authority concept and no author. That fold is not built yet (#1018), and neither is a report over it (#1019).

yidam overlay copies what git tracks

Each subtree overlay copies is now the tracked set under it (#984). yidam/, sadhana/ and samudaya/ used to be walked on the filesystem, minus a list of names. That list is the one #912 took away from yidam clone. It was left standing here. Measured against a working checkout, six gitignored paths under yidam/ were reached by no entry in it. Two .astro/ build caches. Two junit.xml reports. The compiled VS Code extension, and a pytest cache. All six travelled into every repository overlay was run against. That is the half of bootstrap where the target already holds someone's work.

What changes for you. An overlay from here adds no build output and no editor caches. Nothing tracked stopped travelling. As with clone, an uncommitted file in your yidam checkout will not reach the target. Commit it, or at least git add it.

overlay now refuses a source it cannot read a tracked set from. It does not fall back to walking the directory. A fallback restores the whole hole in the circumstance nobody tests. The source has to be a git checkout anyway. The .yidam.toml pin it writes is read from that same git directory.

malformed-yaml reads .yidam/corpus/universal.yml too

yidam lint now gates on a universal-declarations file whose YAML does not parse (#1081). The check covered the four records a corpus is written in after #1056. The fifth file a lint run reads was still read through unwrap_or_default(). A single unclosed quote in it read as a file declaring no universals. Every check that consults them then passed over an empty list. A gate reported clean over declarations it had not read.

What changes for you: a lint run that passed may now fail. Nothing about your corpus changed. The finding names .yidam/corpus/universal.yml and quotes the parser's line and column. Every other finding about that file is suppressed until it reads. A repository with no such file is unchanged and is not reported. Absent is a legitimate answer; unreadable is not.

A document whose yidam: block is not a findings record is reported

New findings-malformed check (#1081). An instance or catalog entry may carry a yidam: block in its frontmatter holding findings. The block is ordinary YAML, so the file parses. malformed-yaml has nothing to say about it. But a block of the wrong shape decoded to no findings at all, silently. Three shapes did, all of them legal YAML:

  • A list where a mapping was wanted.
  • A bare string.
  • A mapping whose keys are not the record's.

Each read as a document with no findings.

What changes for you: a document carrying a block nothing could read now fails the gate. The finding quotes the decoding error. A document with no yidam: block is not reported, and neither is one whose block reads. A file whose frontmatter is broken is reported by malformed-yaml as before and is not attributed to the block.

yidam doctor counts all four records, and reads your bundle manifests

yidam doctor (#1081). The corpus line counted instances and classes. It printed N file(s), all readable on a repository with an unreadable catalog entry or decision record. That is the same silence malformed-yaml had before #1056. It was in the command people run to ask whether a repository is sound. The line now counts all four records, and a failure names how many of how many do not parse.

The corpora line now reports an unpacked bundle whose manifest.yml does not parse. That file is where a dependency's commit, genesis digest and index model are read from. Every field in it is optional, because an older bundle format legitimately omits them. So a manifest nobody could read was indistinguishable from an old one. It also switched off the shadow check, which compares genesis digests and stays quiet when either side is unknown. tonpa install now warns on the same condition as it writes the file.

What changes for you: doctor may now fail where it passed. The remedy for a manifest is mise run tonpa-install. The remedy for a corpus file is yidam lint, which quotes the parse error. A dependency that is not installed is reported as not installed, and not also as unreadable.

samudaya audit says when a seed's header did not parse

yidam samudaya audit (#1081). A seed whose frontmatter does not parse was read as a seed declaring nothing. The audit then reported the fields it found missing — kind: first — rather than the reason it found nothing. The parse error is now reported for that file. The field-level complaints are not, since none of them was measured. A seed with no frontmatter at all is unchanged: it has contradicted nothing.

cli/v0.15.0

yidam clone copies what git tracks, and refuses a source that is not the template

A clone is now the tracked set of the checkout it is run from, minus NOT_INHERITED (#912). It used to walk the working tree and subtract a list of names. A clone taken from a working checkout was 2,931 files and 22.7 MB. Of that, 1,436 files and 14 MB was .claude/worktrees/. It was gitignored the day that entry was written, and absent from git ls-files all along. The same hole delivered .local, and dist against dist-*/ was #900.

What changes for you. A derived repository created from here carries no build output, no install prefix and no agent scratch directories. The same clone now measures 1,433 files and 15 MB. Nothing tracked stopped travelling: the exclusions are unchanged, and every one of them is a path somebody committed on purpose.

An uncommitted file in your checkout will not reach the new repository. That is the point of the change, and it is the one way it can surprise you. If you were editing the template and cloning to test the edit, commit it first — or at least git add it.

clone now refuses a source that is not the template (#913). It copies the directory it is run from, and nothing asked what that directory was. From an empty directory it wrote a target holding one file, .yidam.toml. Quickstart §3 leaves the reader in a copy of examples/streamflow. From there it copied 21 files of another domain. It printed Pinned to yidam 2261d6e2 — streamflow's own genesis commit, labelled as a yidam pin. Both exited 0.

What changes for you. clone and overlay are run from a checkout of yidam. An installed binary carries the CLI, not the template, so this is the prerequisite:

git clone https://github.com/goedelsoup/yidam && cd yidam
yidam clone ~/my-corpus

The test is yidam/prelude/ and sadhana/. Those are what a derived repository does not have: bootstrap vendors the prelude away and consumes the scaffold at genesis. So a derived repository is refused too. To move a corpus, copy the corpus.

A clone that has not been bootstrapped is a state, not a failure

yidam doctor reports a fresh clone as a warn and exits 0 (#914). It used to report fail repository … is a git repository with no .yidam/, with the remedy yidam overlay . — overlaying the template onto a copy of the template. graph-check, lint and the other gates said not a yidam repository … Derive one with 'yidam clone <target>', naming the command whose output the reader was standing in.

.yidam/ is written at genesis, which is step 8 of the bootstrap dialogue. Between clone and genesis a repository has a pin and no corpus. That is not a fault. It is the state bootstrap starts from, and all three reports now name it and point at BOOTSTRAP.md.

What changes for you. A CI job that runs yidam doctor and keys on the exit code now passes here, where it used to fail. Three conditions together recognise the state: .yidam.toml present, .yidam/ absent, and at most one commit. A repository that has been worked in and has lost its .yidam/ is still a fail, with the older message. That is a breakage rather than a beginning.

doctor --strict still refuses it, which is the reading a CI job wants. Nothing that gates on a corpus started passing: graph-check, lint, export, schema and bundle exit 1 as before. Only what they say changed.

yidam --help is short, and --help-all is the full listing

yidam --help now prints thirteen commands instead of fifty-eight (#921). It ran to ninety lines, and the eleven <!-- REGEN --> generators — corpus-index, crates-index, bundle-status and the rest — printed above graph, retrieve and query, which are what the tool is for. A reader opening it to find out what yidam does met a maintenance surface first.

What changes for you. Nothing about the commands themselves: every one still exists, still takes the same flags, and yidam <command> --help is unchanged. What moved is where the whole roster is printed. yidam --help-all is the ninety-line grouped listing, * markers and all.

If you parse yidam --help, read --help-all instead. A script deriving the command set from the short listing will now see thirteen commands, not fifty-eight. One deriving the set that writes will see five, not thirty-two. Neither will fail while doing it. That is the one way this change is quiet, so it is the one worth checking. docs/cli-reference.md documents the full surface, and a gate holds it to --help-all.

yidam with no arguments now prints the short listing. It used to print an error about a missing subcommand. Both exit 2; only the text changed.

The web-install, web-dev and web-build tasks are gone

packages/web/ has been deleted, and its three inherited tasks with it (#942). The browser shell read an exported .yiz bundle. #236 closed it by decision. The tasks outlived that decision in mise.yidam.toml, which every derived repository inherits.

What changes for you. mise run web-install, mise run web-dev and mise run web-build no longer resolve. In a derived repository they could not run anyway. Each began with cd packages/web, and the shell was never part of the scaffold. The removal makes that visible in the task list rather than at the prompt.

Nothing replaces them. RFC-0030 records why a rendered reader is a derived repository's own object, not a template surface.

cli/v0.14.0

yidam lint reads a quote set off in a blockquote

A citation that shows its passage under the link is now held to it (#899). The house writes a quote two ways: inline, or set off below the citation.

The set-off fence has been read since #758. The blockquote had not. So a citation carrying its evidence on the page was scored as carrying none.

What changes for you. A citation of that shape may now report slid-line-citation instead of unverified-line-citation. That is Error, and under the baseline ratchet.

The finding is not new rot. The quote was already wrong about the lines; nothing read it. Re-point the citation, or yidam lint --bless if the debt is inherited. The finding names the range the passage moved to, so the repair is a transcription.

The rule is adjacency, as it is for a fence. Everything between the link and the > must be punctuation. It must contain the colon or dash that introduces it. An aside that follows a full stop is not adopted.

yidam policy --format json now emits the report contract, and one key was renamed

All four policy subcommands gained the report envelope (#893). check, eval, gate and test printed their fields with no envelope around them. RFC-0024 named its dependency as "RFC-0001 (the report contract policy check --format json emits on)", so this is the contract arriving, not changing.

The addition is safe to ignore. The envelope carries the report flattened, so every key these commands already emitted keeps its name and its place. A consumer reading .ok, .allow, .deny or .tests needs no change. What it gains is format_version, yidam and root.

One rename, and it is breaking: policy test's passed is now passing. It was a count. This contract gives passed exactly one meaning: the gate verdict, a boolean, in graph-check, regen --check, index-verify and doctor. One key cannot carry two types for two commands. If you read .passed from policy test, read .passing. Nothing else moved: .failed and .changed_by_override are unchanged, and tests[].passed is a different, nested key that was always a boolean.

Why none of this was caught before. report_goldens.rs requires every --format-bearing command to have its fields checked. It found those commands by scanning top-level --help, and clap does not print a group's children's flags. So policy's four — and kuten check, and phase's three — were never in its population. The scan now descends.

yidam phases grew two columns and a fifth state

phases rows carry type and source, and state can now be interrupted (#473). A phase gained a record: .yidam/phases/<name>.yml, written by the new yidam phase start. Where a ref carries one, it decides whether the phase is running or stopped partway. Ref shape cannot see that difference, which is why the value is new rather than a renaming.

report.schema.json declares state as a closed enum. A validating consumer that pinned the four-member list will reject a report carrying interrupted. Widen it. The five members are active, interrupted, settled, rewritten and position, and git::REF_STATES is the roster both sides are held to.

Nothing in your repository has to change, and no phase you already have is affected. Every existing phase/* ref carries no record, reads exactly as it did, and is marked source: ref. RFC-0028 §3 keeps that arm permanently rather than as a migration window. type is absent on those rows, never blank. There is no default phase-type list, and a consumer must render the absence rather than supply one.

If you consume cycle's in_flight or due's phase clock, they now include interrupted phases. Both filtered on state == "active", which was the whole of in flight while active was the only unsettled state. A run that stopped partway is more in flight than one nobody touched today, so it counts.

yidam run is a plan, and the domain-computer indexes gained a column

yidam crates-index and yidam packages-index write a third column (#472). It names the capability that runs that crate, read from .yidam/capabilities.toml. A crate nothing declares gets an em dash. Before, that crate and one implementing a connector produced the same row.

Your regen --check will report those blocks stale until you re-run them. Nothing about your repository changed; the generator's output did. yidam regen rewrites both and the gate goes green again. This is the only thing here that turns a passing gate red.

A fresh step is now skipped rather than invoked. yidam run <step> compares the step's input state to its committed receipt before invoking it, and runs nothing where they match. It used to invoke every time and discard the result when the bytes came back identical. So a calculator's side effects stop happening on a run with nothing to recompute. A log it appends to, say, or a request it makes. Declare ageing_days = <n> on the capability to re-run it on a cadence regardless. That is what the key is for.

yidam run <step> now also runs what the step declares it comes after. after is new, so nothing you have declared can be affected — a manifest carrying it did not parse before. yidam run with no step argument runs the whole manifest, and --dry-run resolves the plan and writes nothing.

yidam run --format json changed shape. It emitted one step's fields at the top level: step, verb, route, committed. It now emits steps, an array of those, beside requested, dry_run, ran, skipped and committed. A consumer reading the old shape must move down one level. The envelope's format_version is unchanged, and deliberately: run's own fields were never in the frozen contract. report.schema.json declares the envelope, not this command's body.

A capability that does not declare its own implementation is now refused by name. The step is invoked in a tree holding exactly what reads resolves to, so run = ["sh", ".yidam/capabilities/x.sh"] needs .yidam/capabilities/** in its reads. Such a manifest never worked; it failed at invocation with sh: no such file or directory. Now it says which declaration is missing.

Committed REGEN blocks no longer report build artifacts

Three gated blocks stopped asserting things no commit carries (#895). The rule is the one cli/v0.12.0 states below. A committed, gated block may only report what every checkout of that commit agrees on.

yidam status drops its index cell. The block no longer renders index present or index not initialized. yidam index-status and yidam bundle-status now write a pointer. Their blocks say where the answer lives instead of answering.

Why. The vector index and the bundle are build artifacts. Neither is in any commit. The blocks stat-ed them anyway, so yidam regen --check answered about the machine.

Measured on one derived corpus, same tree and same commit: moving .yidam/index/ aside flipped the gate. Exit 1 became exit 0. CI has no index and so never saw the failure. It landed on the contributors who had adopted --features index.

What to do. Run yidam regen once and commit the result as a regen: commit. If you move a local index aside before mise run ci, you can stop.

Where the measurements went. yidam index-status and yidam bundle-status still print them. yidam doctor's index check and yidam due's index row still report freshness. yidam status --format json still carries index_present. Nothing reading a report loses a field.

The scaffolded .gitignore now ignores .yidam/index/ and .yidam/bundle.yiz. Only *.lance/ was ignored before, so meta.json and embed.config.json stayed tracked.

Why that matters. yidam index-build writes indexed_commit as the current HEAD. Committing the index then advances HEAD past it by one. The commit writing "up-to-date" was itself the change that made it stale.

What to do. A new repository gets both rules at genesis. An existing one can copy them from sadhana/root/gitignore. If an index is already committed, git rm -r --cached .yidam/index untracks it.

yidam serve --lsp lints an unsaved buffer as a node

A buffer whose file does not exist yet is now checked (#607). Before, no check saw it. Its findings were none, which is what a clean node's are. Now it is a node, if its path is one the corpus walker would accept.

Your editor may show new findings on a new file. They are the findings yidam lint would report once you save. Nothing changes for a buffer whose file is on disk.

The server declares it. The initialize result carries experimental.yidam.unsavedInstances: true. A client that needs this can check for it.

A seat can say what it holds, and yidam lint reads it across the seat's own history

Four new findings about ma/* branches (#294). A seat may now keep .yidam/sangha/commitments/<elector>.md on its own branch. It carries two sections, ## What this seat holds and ## What this seat has withdrawn. Each item links the position that argued it. The file is never transported onto the baseline.

One new Info finding fires whether or not you adopt it. elector-commitments-absent reports a seat that has filed a position and carries no commitments file. A repository with three such seats gains three Info findings and nothing else. Your exit code does not change. The other three are silent until a commitments file exists.

Two of the other three gate, and only over a file you wrote. elector-commitments-malformed is an Error when the file does not carry both headings. A file with no headings parses to two empty sections, which would turn the next check off. elector-commitment-vanished is an Error when a ground disappears. A position named under holds at one commit, and in neither section at a later one, is the finding. Deleting the file counts, because it takes the grounds it held with it. elector-position-unindexed is Info and reports one of the seat's own positions that neither section names.

The item's identity is the position it links, never its prose. Reword an item freely. What must not disappear is the link. Moving it to ## What this seat has withdrawn is always the answer. Withdrawing a ground is the act the loop exists to produce, and is never reported.

The commitments file is read from the branch, so a thin clone reports less rather than differently. A checkout without the ma/* commits sees no seats at all, like resolution-independence-mismatch. Fetch the elector branches to get the real answer in CI.

yidam lint now derives a resolution's independence:

New Info finding, resolution-independence-mismatch (#823). It reports a record whose stated independence: is not the one its seats derive. The derived value rides in the finding, so the finding is also the repair. Info, not a gate: your exit code does not change.

It is silent unless your registry binds Kind, Model, Version and Config. Without those columns every record derives unrecorded. A record that states nothing over an unrecorded derivation is passed over. Filling the columns in is what arms it.

The registry is read at each seat's own tip, not at HEAD. A checkout without the ma/* commits reads unrecorded rather than falling back. --depth 1 and --single-branch are both that checkout. So a record that does state a value will report there. Fetch the elector branches to get the real answer in CI. resolution-scope-unverifiable already warns about the same thin clone.

yidam sangha --json gains resolutions[].independence, a string, empty where the record carries none. Not required by the schema, for the reason synthesized_by is not.

cli/v0.13.0

Several corpora can share one vector index, and a query can ask across them

MCP contract 0.23.0 → 0.24.0. retrieve takes an optional corpora argument, every response carries scope, and every result carries corpus (#835). A server built against 0.23.0 answers every call unchanged. A client built against it never asks to span, so nothing it does today behaves differently.

Nothing on disk or in a bucket moves. Vector keys have carried the corpus since the first push. So has corpus, as a filterable metadata key. An index several corpora already push to can be asked a spanning question, with no re-push by any of them.

Only a remote index can answer one. A local .yidam/index/ is one corpus by construction. A call that asks to span it is not an error. It is not silently honoured either: it answers locally and reports scope: "local". Compare scope against what you asked to know whether the span happened.

A result from another corpus cannot be fetched. Its id is the reference grammar's absolute form: yidam://<corpus>/node/<class>/<name>. get_node cannot resolve it, because that corpus is not installed here. Its text is all you get. corpus is null for this server's own rows, so a client can tell the two apart without parsing anything.

corpus is not origin. origin names an installed dependency under .yidam/tonpa/, whose nodes this server read and whose ids it resolves. A corpus that merely shares an index is neither. One word for both would say a row is followable when it is not.

yidam retrieve, and one vector space per index

A new command, and a new refusal from index-push. Neither changes a corpus. yidam retrieve <words> is the retrieval serve --mcp performs, dispatched through the same tool call, with --k, --class and --corpora. It had no terminal route before.

index-push now refuses an index built in another vector space. An index carries one embedding contract and every push overwrites it. Two spaces in one index would let a spanning query rank one corpus's rows against the other's. The scores would look ordinary. If your push starts refusing, that index already holds a contract your embed.config.json disagrees with. Push to a different index, or rebuild with the settings it declares.

Where the contract cannot be read, the push proceeds and says so. A write-only credential is a legitimate shape for a pusher. So a 403 on GetVectors is a printed note, not a refusal. A push also now reports the other corpora it found in the index, with a row count each. --dry-run is the read-only way to ask.

yidam migrate findings lifts the questions an earlier propose wrote

A finding is a record under the node's yidam: key. It used to be an English sentence appended to description:. It was found again by grepping the prose for its opening words. Paragraphs an earlier release wrote are still recognised and still closed. Nothing was stranded, and nothing here is urgent. This is the one-time lift (#728).

yidam migrate --dry-run findings   # what it would do
yidam migrate findings             # do it

Two numbers move, and only for a corpus that runs it. The [open] claim counts drop. A carried question stops being counted among the claims the corpus makes. That is the whole point of the record. open-questions does not change: the record is still an open question on the node.

A corpus publishing a claim tally in a generated block will see that tally fall. Roughly by the number of questions propose has open. Re-run yidam corpus-index after the lift.

A paragraph you reworded stays prose. The lift matches the marker, the check in brackets and the fixed framing sentence exactly. A sentence you rewrote is yours, and this will not guess where the tool's words ended. Those are counted in the report and left alone, [open] tag included. So a reworded paragraph keeps counting as a claim until you decide otherwise.

A catalog entry with no frontmatter is refused rather than lifted. Removing the paragraph there would leave nowhere findable to put the record. The run reports the file and writes nothing at all.

The migration is idempotent and writes a record under .yidam/migrations/.

A retrieve result says whether its text is all of it

MCP contract 0.22.0 → 0.23.0. Every entry of results carries truncated, a boolean (#853). It is false on keyword search and on a local index. Neither has a per-row ceiling to cut against. Only a corpus served out of a remote vector index can answer true. A server built against 0.22.0 still answers every call. A client built against it reads a cut row as a whole one, which is the state this ends.

A remote index stores each row's text under a 40 KB ceiling. yidam index-push already cut the rows that exceeded it, and already said so in its report. What was missing was the other end. The flag travelled back with the row and retrieve dropped it. So half a document rendered exactly like all of one. Nothing about what is stored changes here, and no index needs rebuilding.

Expect almost no true. Across sixteen measured corpora, one row in 3,246 is cut. It is a catalog source rather than a node. A node's text is the fields somebody wrote; a source's is a whole markdown document that no format caps. A remote index over catalog sources is where this bites. It is where you find out which of them you have been reading half of.

An edge may no longer assert a standing its endpoints contradict

edge-standing-unheld is a new warn (#858). It reports an edge asserting a standing stronger than one its own endpoints declare. claim_tag: verified between two nodes graded [open] claims more about the relation than the corpus claims about either end.

It reports in every corpus, with no declaration, like edge-verified-unsourced. Writing the tag is the opt-in. A relationship listed under structural: is not exempt. Bookkeeping that asserts more than the nodes it files has stopped being bookkeeping.

A node's standing is a property its class declared type: claim. Nothing else. Not the weakest marker in its prose. A synthesis node carries all three tags by design, so reading its weakest would grade your best-made nodes [open]. A corpus whose classes declare no claim-typed field therefore sees nothing here, however its edges are tagged.

It is one-directional. An open edge between two verified nodes is never reported. Such a corpus knows both things and does not say they are related. That is the vocabulary working.

This check's population is not empty by construction, and it is the only one here. That is why it is warn, and why it stays warn. Both sides of the comparison are opted into separately. So a corpus can adopt edge tags on nodes graded years earlier, and inherit findings it did not write. The repair is a demotion on the edge, or a promotion on the node with a reason. Nothing proposes the promotion for you. yidam lint reports more findings and mise run ci passes.

An edge's standing is now counted and listed, and where it used to be counted it was the node's

claim_tag on a link was graded by two lint checks and read by nothing else. open-questions, status, corpus-index and the MCP claims and open_questions tools now read it too (#857). A corpus that tags no edge sees none of this. Every figure and every table below appears only where there is something to report.

A bracketed edge tag stops being counted as a node's claim. A link writing claim_tag: "[open]" was visible to the byte scan over the node's file. That is the spelling a corpus adopts after being told the prose scan needs brackets. So the edge's standing was already being reported — as an [open] in the node's own prose. It now belongs to the edge.

If your corpus writes the bracketed form on links, expect three things. status and corpus-index will show fewer node claims. A new edge figure will carry the difference. And the node will leave open-questions, with the edge arriving in its own right. The bare form — claim_tag: open — was never counted anywhere and only gains.

status and corpus-index grow a second figure rather than a bigger one. claims still counts a node's prose and its claim-typed properties; edges is the same three over its links. A corpus-wide total is the two added, and nothing adds them for you. An edge is in no node's text, and it belongs to two nodes at once. One merged number would answer about a denominator nobody chose. The edges segment and the Edges column render only where some edge is tagged. That keeps yidam regen --check green in a repository that has not made the distinction.

An open edge is its own entry in open-questions, not a promotion of the node. It is listed under the node's label, with the triple beside it. The link still points at the node, because that is the file it is written in. The JSON gains scope — node or edge — on every entry, and relationship and target on the edge ones.

MCP contract 0.20.0 → 0.21.0. claims serves edge claims with scope: edge; open_questions gains the edge arm and scope on every entry. A server built against 0.20.0 still answers every call, because the additions are new fields and new entries. But it under-reports a corpus that tags edges, in exactly the way the CLI did before this.

An edge may say what it rests on, and a verified one is asked for a source

A link could always be written with extra keys and nothing read them. claim_tag: and source: are now part of the link shape, and two checks read them (#587).

edge-verified-unsourced reports in every corpus, with no declaration. A link writing claim_tag: verified and no source: is a new warning where there was none. Tagging edges is the practice this came from, and the published schema used to underline it as invalid. If your corpus does it, expect one finding per verified link with nothing behind it. The repair is a source: or a demotion to inference. Which of the two is yours to decide; nothing proposes a promotion.

edge-untagged reports nothing until you ask for it. Its population is every edge, so it runs only where .yidam/corpus/universal.yml says so:

edge_claims:
  required: true
  structural:
    - instance-of
    - concerns
    - subject-of

structural: names the relationships that are bookkeeping rather than empirical. Both keys are new and both are optional; a corpus that writes neither is checked exactly as it was. Writing structural: alone records the exemption and switches nothing on.

Both checks are warn, so neither reaches the baseline and neither turns the gate red. yidam lint reports more findings and mise run ci passes.

The editor stops underlining the two keys. The link item in the published node schema listed target, relationship and note, and closed the object. So a corpus writing edge provenance got a red squiggle on every tagged link. Rerun yidam schema to pick up the new shape, and edge_claims: in the universal.yml schema with it.

The MCP contract has a write tier, and a server's corpus snapshot is no longer fixed at startup

The contract goes to 0.22.0 and gains one tier, act, holding two tools: propose and cycle. Both are absent from every server that has not been told to write. That is every server today, so nothing about an existing deployment changes until somebody writes the key.

Two things to know if you consume this surface.

The freshness sentence narrowed, and today nothing you can read moves. Contract 0.9.1 said that every read came from the corpus built on disk at startup. Freshness was a restart. That is now startup, or the server's own last write.

A change made outside the server is still invisible until a restart, exactly as before. An edit, a tonpa install, a commit from another process: all unchanged.

The second half is the part worth having before you change any client code. propose builds its commits against a temporary index and creates the ref with update-ref. The working tree is untouched and HEAD does not move. Every read tool answers byte-identically across the write.

So the reload is a correct no-op for the only write this tier has, and no response observably differs. The rule is in the contract for two reasons. It costs one corpus re-walk on a call that already wrote to git. And the first act tool that touches the working tree should not also have to be a contract change.

If you cached a handshake's corpus.commit, it is still correct today. It is no longer guaranteed to be.

act is the one capability in the block that is permission rather than ability. Every other key is filled from what the server can back. This one is false unless the corpus says otherwise, even on a server that could write perfectly well. A client must never infer it.

To turn it on, in the corpus's own .yidam/config.toml:

[serve]
act = true

And three clauses must hold, or the server refuses to start rather than quietly serving the read tools:

  • a git author identity resolves in the corpus being served — user.name and user.email, the values the commit would take. A checkout with none cannot declare act on any transport, stdio included;
  • the declaration is this key and nothing else. A flag would make may a tool write into this corpus a property of whoever launched the server;
  • serve --mcp --http binds loopback. A server reachable from another machine may not declare it, because no author exists for a remote caller yet.

The refusal is the point rather than an inconvenience. An operator wrote the key and got a running server. They would read that as the answer to the question they asked.

What propose may write is unchanged from the CLI. Three verbs go onto a propose/<head> branch: open, withdraw, close. Never onto the baseline, and nothing merges itself.

There is no --force on this surface. Replacing a proposal branch discards commits nobody has reviewed, and that repair is a person's.

yidam cycle also ships as a CLI command, available in every build and needing none of this.

used-by: [] is now a claim the drift check reads

catalog-used-by-drift compares a catalog entry's declared used-by against the nodes that cite it. It skipped that comparison whenever the list was empty. An empty list and an absent key arrived at the check as one value. So used-by: [] was a silent opt-out.

An entry sitting at used-by: [] while nodes cite it now draws a warning it did not draw before. Nothing in a repository changes to bring this about. It is the state a hand-authored entry starts in. The entries most likely to be affected are the newest ones.

used-by: with no key at all is unchanged and still exempt. Absence declares nothing. A command that filled it would decide an entry should make a claim its author never made. The two states have always been different; only one of them was being read.

The gate does not go red. The check is warn severity, and warnings never reach the baseline — yidam lint reports one more finding and mise run ci passes. The repair is:

yidam catalog-reconcile

which substitutes the citations for the empty list and commits as reconcile:. It still leaves an entry with no used-by: key alone.

One thing to know if you read the report rather than the terminal. In catalog-audit --format json, the drift field distinguishes the two states and used_by does not. Both render as []. drift is null for an absent key, and an object for a declared-empty one. A client switching on used_by.length === 0 was never telling them apart and still is not.

degraded_reason has a fourth value, and it is not a property of the deployment

The MCP contract goes to 0.20.0. retrieve and an anchored query may now report remote_unavailable, alongside no_index, no_vector_support and stale_contract.

A client that validates the field against a closed set of three will reject a valid response. Nothing in a repository changes to bring this about. The new value appears when a corpus declares [index.remote] and the service behind it does not answer.

If you wrote that validation, widen it. The set is frozen in yidam/sdks/parity/mcp/tools.json, which is the file to read it from.

There is a second thing to know, and it is the part a cache gets wrong. The three older values are properties of a deployment: true when the server starts, true for its lifetime. The new one describes a call. A server may report it on one request and nothing on the next. A client that reads degraded_reason once at handshake and remembers it will be wrong about its second question.

Nothing else moves. A corpus that declares no [index.remote] — which is every corpus today — answers exactly as it did.

yidam regen now populates two more blocks, so --check can newly fail

vault-status and decisions-log write REGEN blocks. yidam regen did not run either of them, and yidam regen --check did not report them stale.

Both now run, and mise run ci can go red on a repository nobody changed. The README's Artifacts block is the one to expect. Most corpora still hold the placeholder the template ships there — the italic line telling you to run the generator. It was never checked, so it never had to be true.

The repair is the ordinary one:

mise run regen
git commit -am 'regen: populate the vault-status block'

Read the diff before committing it. The block reports the arrangement your .yidam/config.toml declares — which stores exist, who may read each, what routes where. If it says something you did not intend, the block is right and the configuration is the thing to fix.

Two other corrections travel with it. yidam decisions-log no longer describes itself as read-only; it writes a block when .yidam/decisions/README.md carries one. And yidam policy no longer carries the * write marker in --help, because it writes nothing.

A property can be retrievable without being prose

prose: true, added in cli/v0.11.0, is right for what a node says. A gage's parameter and its units are not that. Neither string was in any vector. A query for cubic feet per second could not reach the node that writes the phrase. Identifiers, codes and units are what a reader types verbatim, and they were the part excluded.

Flagging them prose: true would reach the embedding. It would also make node-too-long count the code. And missing-description would accept a node that says nothing but the code. So there is a second flag:

# <class>.ont.yml
properties:
  - name: parameter
    type: string
    retrievable: true
    description: The measured quantity, by its publisher's parameter code.

Who this affects. Any corpus keeping identifiers, codes or units in a property. Nothing changes for a corpus that flags none. Absent means false, exactly as required: and prose: are.

What changes when you flag one. No report. yidam embed composes the property, and nothing else reads the flag. So re-run yidam index-build, and expect no movement in lint. A property already flagged prose: true needs nothing. Prose reaches the embedding already, and a property flagged both is composed once.

What it does not reach. A property holding anything but a string. A prose key holding a list is not prose either. It is a real state, and guessing a rendering would put words in the corpus's mouth.

cli/v0.12.0

The README status block no longer counts phases, and refuses a shallow clone

Two changes to yidam status and one to yidam regen. Both follow one rule: a committed, gated block may only report what every checkout of that commit agrees on.

Phase counts leave the block. yidam status no longer renders N active phase(s) into the README. The counts read branch refs, and which refs a checkout holds is a property of how it was fetched. So for one commit there was no value that passed yidam regen --check everywhere. A default CI checkout and a machine that had run git fetch wanted different numbers. The gate was unwinnable rather than wrong. The count also moved with no commit at all. Pushing a phase branch reddened the gate on every open pull request.

What to do. Run yidam regen once and commit the result as a regen: commit. Your block loses one cell. Your CI may have added an all-branches git fetch to make the two agree. It is no longer needed for this. Check whether anything else you run wants it before removing it.

Where the counts went. yidam phases prints them, and being current is the point there. yidam status --format json still carries active_phases, settled_phases, rewritten_phases and positions. Nothing reading the report loses a field.

yidam regen now refuses a shallow clone. The block reports the corpus genesis, which is the repository's first commit. A --depth 1 checkout does not have it, and git does not say so: it names the boundary commit a root. The block was therefore written from a date the clone invented, and --check asked you to commit it. Measured on one corpus: genesis 2026-08-28 from a full clone, 2026-09-07 from a shallow clone of the same commit.

What to do. Check out with fetch-depth: 0, or run git fetch --unshallow. The scaffolded .github/workflows/ci.yml already does the former. If yours does not, this step now fails with a refusal naming the remedy rather than reporting a stale block.

genesis reads unknown in a shallow clone, in every command, not just this block. That is the same change from the other side. A corpus whose history is absent has no genesis to name. yidam bundle writes genesis_hash: null there, which consumers already handle.

A qualified evidence tag is now a claim, so two numbers move

[verified — as proposed] used to match none of the three tokens exactly. It counted as no claim at all. claim-tag-malformed filed a finding on it, and that finding's own advice was that there was nothing to do. Such a tag now reads as one claim at its standing. It carries the qualifier as free text, and the finding is gone.

Two numbers change in your corpus, and neither is a defect.

  • Claim counts rise. yidam status, corpus and the claims MCP tool all count the tags they were silently dropping. Run yidam regen so the README blocks that publish those counts agree again. A stale REGEN block is a failing build in a derived repo.
  • claim-tag-malformed findings fall, by exactly the number of claims gained. Your .yidam/lint-baseline.yml will report them as expired. Run yidam lint --bless once.

Measured over the six corpora that write these details, 38 findings became 38 claims. Three corpora move by nothing; the others:

corpusfindingsclaims
ohio-education-funding535 → 5061362 → 1391
allen-recorder13 → 6420 → 427
demi-moore10 → 81678 → 1680

What is unchanged. A bracket that folds in a citation — [verified — Pearl 2009] — is still not a tag, and still reported; move it into references:. A bracket holding two standings — [verified for the arithmetic; inference for the reading] — is still not a tag either. Its advice now says so: write two claims. Nothing on disk needs editing for this.

The MCP contract goes to 0.19.0, because it is the contract that states what counts as a claim.

A bundle now says which corpus it is

manifest.yml gains genesis_hash: the full SHA of the corpus's first commit. genesis was already there and is a date, so it can order two bundles and cannot tell them apart. Two corpora created on one day share a date; no two share a root commit.

bundle_version stays "1". Adding a field is not a breaking change. Nothing that could read a bundle before can fail to read one now. Nothing on disk needs editing. Rebuild with yidam export --format bundle for a bundle that carries the field. Bundles you have already published stay valid without it.

If you read manifest.yml yourself, absence means the corpus is unidentified. It does not mean zero, and no placeholder should be substituted. One constant would name every bundle built before this alike — the confusion the field exists to prevent.

yidam doctor's corpora check uses it for one new finding. A path dependency and an unpacked bundle can claim one name, and the checkout is what gets read. That is normal when the two are one corpus in two forms. It is a failure when their genesis hashes differ, because then tonpa.lock pins a corpus nobody is reading. The check is silent when either hash is unknown.

export, bundle and schema refuse a directory that is not a corpus

They used to succeed. In a directory with no .yidam/, every export format wrote an artefact and exited 0. An empty bundle, an RDF graph of nothing, a llms.txt with no nodes. --format bundle, --format web and schema also created .yidam/ on the way, which is the marker every check tests for. One run in the wrong directory left a tree that graph-check, lint and doctor would all accept.

If a script of yours runs one of these outside a corpus, it now exits 1 and names the directory. That is the change to look for. Nothing changes inside a repository, and an empty corpus still exports. An hour-old repository with no nodes is a corpus, not a missing one.

schema --settings is unaffected. It prints a compiled-in editor mapping and reads no corpus, so there is nothing for it to refuse over.

A corpus nested in another repository has no identity, and RDF export says so

genesis_hash — the corpus's first commit — was read by running git at the corpus root. Git resolves upward, so a corpus that is a directory inside a repository was described by whichever repository encloses it.

Every corpus under this template's examples/ was in that position. All four minted RDF subjects under urn:yidam:094509a128f4, which is the template's own first commit. Their four owl:Ontology resources were one resource asserting four different labels.

export --format rdf now refuses such a corpus rather than naming it with its host's identity. manifest.yml's genesis_hash is null for it, and genesis reads unknown instead of the host's date. Every other export format is unaffected: only RDF names subjects.

If this affects you, give the corpus its own repository. Copy it out and git init there, or yidam clone a fresh one. A corpus that is already its own repository changes by nothing, and no subject that was correct before moves.

That is why this refuses rather than falling back to the corpus's own earliest commit. Such a fallback would have kept the four exports working, and changed each identity the day its corpus was extracted.

A phase merged with GitHub's rebase or squash button is no longer counted as active

yidam status and yidam phases decided a phase had settled by asking whether its ref is an ancestor of the baseline. That is true only of the merge PHASES.md prescribes — --no-ff, keeping the synthesis event.

GitHub's Rebase and merge and Squash and merge both write a single-parent commit onto the baseline. Neither moves the branch tip. So the ancestry test was false, permanently, and the phase read active forever. One repository reached 22 phases in flight, every one of them complete. The number could not fall from inside the repository, because it is computed over refs.

Your active-phase count may drop, and that is the fix rather than a loss. Those phases now read rewritten — settled by a merge that rewrote their commits. yidam status names them separately from settled, because the repair is different. The ref can never become an ancestor, so deleting it is the only way the count falls.

If you consume the JSON, status --format json gains rewritten_phases, and phases rows can carry state: "rewritten". It is a new field rather than a fold into settled_phases. A consumer watching active_phases fall needs somewhere to see where the difference went.

One case is knowingly not covered: a squash-merged branch whose files the baseline later edits again still reads active. Detecting it needs the branch's combined patch searched through the baseline's history, which is exact and unbounded in cost. The error is in the safe direction.

cli/v0.11.0

score says why the criteria are the template's, in four states

score read a range's kuten at the range's tip. Then it wrote a sentence about the repository. A range ending before your adoption said you hold no kuten. So did a range whose declared profile is not vendored. That state is one kuten check and doctor both warn about.

Who this affects. Anyone scoring a range older than their adoption. That is nearly every range: both early adopters declared in their last two commits.

What changes. The report names one of four states. The unreadable-profile state is now a warning. --format json gains source, declared and holds_now.

One JSON field narrows. revision used to carry what the range's tip declared, even where the criteria were the template's. A record could read held: false beside revision: 1. It is now null whenever held is false, and what the tip declared is under declared.

query's rejection codes: three you may be matching on have never fired

rejected.code is frozen so a client can branch on it without matching prose. The frozen list and the codes serve --mcp actually emits had never been compared. They disagreed in both directions for nine contract versions.

Three frozen names are yidam lint check ids, and no query rejection has ever carried one — unknown-property, unlicensed-edge, edge-target-class. They are gone from the list. Five the server does emit were frozen nowhere and are now in it: undeclared-property, unlicensed-hop, unsatisfiable-predicate, unordered-property, anchor-across.

Who this affects. Anything branching on rejected.code — a custom MCP client, or a script reading yidam query --format json.

Why this is more than a spelling. unknown-property and undeclared-property are the same thing to a person and different strings to a match. The else arm of such a branch is usually unknown rejection. So a misspelled property name arrived unclassified at the caller the code set exists to serve. Silently, and in the direction that hides it.

The repair. Compare your match arms against the list in yidam/sdks/parity/mcp/tools.json. Arms for the three removed names are dead code; add the five. diagnostics[].code is enumerated in the same file for the first time. A client can branch on that too, rather than matching its prose.

yidam propose records a question instead of writing a sentence

A question this tool opened used to be a paragraph spliced into description:. It was found again by searching the prose for the sentence it had written. It is a record under the node's yidam: key now. The key is a digest of the check and the finding's words.

Who this affects. Any corpus that has run yidam propose.

What gets better. A question survives an author rewriting the node's prose — it is closed by id. A carried question stops being counted among the corpus's own open questions. And a node whose description: is a plain scalar can now be asked about at all. It used to be refused: a paragraph could not be appended without reformatting a line.

Nothing strands. Paragraphs written by an earlier release are still recognised and still closed when their finding goes away. Lifting them into records is not automatic; the questions stay askable and closable either way.

One number moves. The [open] claim counts drop by however many questions this tool had carried. Those were never the corpus's own. yidam open-questions still lists the nodes, so what shrinks is the claim tally and not the worklist.

Prose is what the ontology declares, and description is no longer required by name

node-too-long and missing-description read description and nothing else, while the claim counter reads the whole file. A corpus keeping prose in a summary or a findings was measured on a fraction of what it wrote. One reads 21 lines a node against a true 34. And a node with a summary and no description was reported as having nothing said about it.

A class now declares which of its top-level keys hold prose. The corpus may declare it once for every class:

# <class>.ont.yml
prose: [findings]

# universal.yml
prose: [summary, findings]

The effective set is {description} ∪ universal ∪ class. description never has to be listed and naming other keys does not unname it.

Who this affects. Any corpus writing prose in a top-level key other than description. Nothing changes for a corpus that does not: absent both declarations the set is [description], exactly as before.

What changes when you declare. node-too-long counts more lines, so findings may rise — this is the number the ceiling was always about. missing-description findings fall. yidam embed composes the full prose, so re-run yidam index-build. An index built before this embedded a node's label and its edge names. It did not embed what the node said.

description has also been dropped from the node schema's required list. The check no longer asks for that key by name. An editor will stop underlining a node that says what it knows in a field the corpus declared.

A property can hold prose too

The declaration above reaches a top-level key. Most prose that is not in description is not there. Measured over sixteen corpora and 2,763 nodes: 68.6% hold a nested block scalar. 83% of that sits under properties:. A method or a verbatim is the node saying something. Nothing that read prose could see it.

A property now says so itself:

# <class>.ont.yml
properties:
  - name: method
    type: string
    prose: true
    description: How the figure was computed.

Who this affects. Any corpus keeping prose in a property. Nothing changes for a corpus that flags none: absent means false, exactly as required: is.

What changes when you flag one. node-too-long counts those lines. On one public corpus, flagging 14 declarations moved it from 58 findings to 94. That is the length those nodes always were. missing-description stops reporting a node whose substance is a transcription in a property. And yidam embed composes the property, so re-run yidam index-build. On that corpus the flag adds 10.4% more prose and rewrites the text of 380 nodes of 694.

What it does not reach. Prose under links:, and prose nested under a coined top-level key. Together those are 17% of the nested prose measured. The first belongs to the edge vocabulary. The second needs a class contract that describes the key. Neither is in this release.

A baseline holding the old counts still passes, so nothing goes red. It also leaves room for regressions that nothing will report.

The inquiry kuten is at revision 2, and two bands are gone

nodes-per-commit and median-node-lines measured how old a repository is, not how it works. Nothing read them at matched maturity, and every member of the fit exits both bands by ageing. One left both within six hours of the fit that used it.

Who this affects. Any repository holding inquiry. Nothing is broken and nothing gates.

What changes. kuten check reports three findings where it reported five. The AGENTS.md block loses its Shape line. The two numbers are still measured and still in the report; no band judges them.

The repair. Re-vendor, then record a superseding decision:

YIDAM_REF=v0.5.0 mise run yidam-vendor-update

Until you do, doctor warns that your record names revision 1 and the vendored profile is at 2. That is the revision model working, not a fault.

kuten check rows read in one unit, and a divergent row says which side

A row read declared 0.12–0.27 measured 12% — two halves of one comparison, in two units. Worse, 12% is inside 0.12–0.27 when you convert it, and the row was reporting divergence.

Who this affects. Anyone reading kuten check, and any consumer parsing its JSON.

What changes. Bands render in the value's unit: declared 12%–27%. Shares carry a decimal: measured 11.9%. A divergent value names the side it fell on: 11.9% (below 12%).

Why the last one. The verdict compares a float and the display was rounded. So a divergent row could show a number that reads as inside its own band. Precision alone cannot close that; naming the side can.

cli/v0.10.0

A corpus can declare what its practice is aimed at

yidam kuten is new. A kuten declares what this corpus's work is for, as the ontology declares what it is about.

It ships as vendored prelude and carries a revision. A decision record adopts it. Holding none is a supported state, and it reports as one.

Who this affects. Every repository, on its next re-vendor. Nothing changes until you adopt one.

The repair. Nothing is broken. To adopt, re-vendor and then declare:

YIDAM_REF=v0.4.0 mise run yidam-vendor-update
yidam kuten adopt inquiry

adopt copies the revision out of the vendored profile rather than asking for it. It also adds the AGENTS.md section and fills it, because the scaffold carrying that section is consumed at genesis.

Where there is no AGENTS.md at all, it writes none and says so. It prints the section for you to paste. yidam doctor reports it until a file carries the block.

Then yidam kuten check reads your history against what you declared. It writes nothing and exits zero however far a corpus has drifted.

yidam score <range> reads a session's work

The genesis rubric scores a repository's birth, once. Nothing said whether a session's work was any good.

score reports one row per declared criterion, each with the evidence it came from. There is no overall number: a single score over a range names somebody's session.

Criteria come from the kuten's rubric slot, or from the template where no kuten is held. The report says which, every time.

node-too-long counts the description, and your baseline is now loose

The check counted the whole file — frontmatter, properties and links included — while its own rationale argues about prose. The two came apart once corpora began recording where their edges come from.

One derived corpus reported 212 findings, and 207 came from a single class. Its fixed structure runs 18 lines before a word of prose.

Who this affects. Any corpus whose nodes record provenance on their links. Findings fall, often sharply.

The repair. Re-bless after upgrading:

yidam lint --bless

lint --commits can be scoped to the corpus register

A repository with an artifact beside its corpus has two commit registers, and yidam modelled one. A feat: on web/ was reported as a corpus-vocabulary violation.

Name the artifact's paths and it no longer is:

[object]
paths = ["web/**", "crates/**"]

Who this affects. Nobody who leaves the key unset. The default is unchanged.

One asymmetry, deliberate. yidam vocabulary --check reads a subject line before the commit exists. It cannot ask git for paths, so it still warns where lint now stays quiet. Its callers are a contributor at a terminal, the VS Code commit box, and the MCP tool check_subject. Tracked as #652.

Corrected 2026-09-07 (#693): this note first named a commit-msg hook, which this project does not ship.

A citation naming a line is held to what the line says

lint now checks #L42 fragments on prose links, reading the quoted passage against the lines cited.

Who this affects. Repositories whose prose cites files by line number. Most do not.

cli/v0.9.0

serve refuses a directory that is not a corpus

yidam serve --mcp and serve --mcp --http now fail at the command when started somewhere with no .yidam/ directory, instead of starting and serving an empty corpus.

Who this affects. Anyone whose MCP client launches the server from a directory other than the corpus. That configuration was always wrong and never said so, which is why this is worth reading rather than merely noting: the symptom changes from a server that answers every question with nothing into a server that does not come up.

The old behaviour was worse than "serves nothing". The handshake for a directory that was not a corpus was identical in shape to one for a repository bootstrapped an hour ago — nodes: 0, skills: 0, decisions: 0 in both — and the only field that differed, domain, was derived from the directory's own name. An agent had no way to tell "this corpus is empty" from "this is not a corpus", and the warning that would have said so went to stderr, which an HTTP client cannot read.

The repair. Point the client at the corpus. For a client that starts its servers somewhere else, pin it:

{
  "mcpServers": {
    "yidam": {
      "command": "sh",
      "args": ["-c", "cd /abs/path/to/my-corpus && exec yidam serve --mcp"]
    }
  }
}

The Claude Code plugin does this for you and checks before it spawns.

What is not affected. A repository that has been bootstrapped and has nothing written into it yet is still served. The test is .yidam/, not corpus content — an empty corpus is a legitimate corpus, and saying otherwise to its author is the one thing this change must not do.

See #549.