[aaltshuler]

Refresh the OmniGraph skill and operator guides for the released 0.13 workflows. Replace accumulated restart workarounds, removed HTTP routes/flags, and duplicate instructions with current live deployment, exact-receipt, policy/provider, and graph lifecycle guidance.

Keep all 13 skill reference filenames stable for the MCP bundle. This removes roughly 1,100 net lines while correcting policy-update, embedding-provider, and served-plan documentation.

Validation: skill validator, documentation checker (213 Markdown files), agent-guide links, typos, and diff whitespace all pass. No engine behavior changes.

[aaltshuler]

Keeping this PR open: the current head 2990fa3 has one incomplete qualification result. Azurite Azure Integration exceeded its 90-minute job limit and was cancelled while compiling. Tests that had executed passed, but the remaining Azure qualification and final inventory check did not finish.

The other required checks completed successfully. This is a CI completion blocker, not evidence of a failing test assertion. Complete the Azure job before merging; do not waive the gate. No rerun or workflow change was made as part of this issue-cleanup pass.

[cursor]

Review of 2990fa3 — recommendation: request changes (rebase and re-cut on current main)

This is posted as a comment because this reviewer cannot submit a formal review event. Read it as Request changes.

Why, what, how, impact

• Why: The skill and operator guides had stale 0.12-era text: removed routes, removed flags, a false "policy edits are refused" rule, and wrong secret-resolution timing.
• What: This PR rewrites 20 files (+812 / −1,900). It cuts duplicate text and fixes those facts for 0.13.
• How: It rewrites whole files, mainly SKILL.md, commands.md, cluster.md and the deployment/cluster guides.
• Impact: The factual fixes are correct and main still needs them. But the branch is based on v0.13.1 (8ca09c15) and main has moved 96 commits. On main the rewrite breaks a machine-checked contract and states facts that are no longer true. Do not merge it as is. Rebase it, or re-cut it as small edits on current main.

Blocking findings

1. The branch cannot merge. GitHub reports CONFLICTING. A trial merge onto main 4d7536d6 conflicts in 5 files (13 hunks): SKILL.md (3), references/commands.md (5), references/schema.md (1), docs/user/deployment.md (2), docs/user/operations/upgrade.md (1). main has changed 11 of the 20 files since the merge base. Six open PRs also edit these files: feat(cli)!: derive omnigraph embed vectors from the schema's @embed declarations #952, feat(server): add optional OTLP traces and correlated JSON logs #1001, feat(server,cli,mcp): report each branch's head, start and times in the branch listing #1012, feat(commits): page a branch's commit list #1013, feat(branch): start a branch at a graph commit #1016 and fix(cli)!: send a server token only to the server it is keyed to #1030.
2. The rewrite fails main's skill-to-CLI guard tests. On main, crates/omnigraph-cli/src/skill.rs holds the skill to the clap tree (the omnigraph-skill row in docs/dev/testing.md). That keeps one source of truth for command names. This PR deletes the three sections those tests parse. Inline comments give the details.
3. Version-pinned text contradicts main. main reports internal-schema 16 (serves v14 to v16) and ships a version-matched skill (omnigraph skill export / skill show). The PR says "0.13 only, serving storage format 14" (SKILL.md) and "OmniGraph 0.13 opens storage format v14" (upgrade.md). Its changelog note says "current 0.13 workflows", but it would ship in the 0.14 notes.
4. The writer-lock text contradicts main. cluster.md and deployment.md say a server keeps the cluster lock even after a clean exit, and give a force-unlock-before-serving procedure. After feat(server): release native admission after settled clean shutdown #899 and feat(cluster): transfer fresh S3 bootstrap ownership to the first server #893, main releases admission on a settled clean shutdown on local and S3 storage. Azure still keeps the lock. A fresh S3 bootstrap can pass ownership to the first server with --bootstrap-handoff. An agent that follows the PR's text would run force-unlock when no lock is left to clear.

The category for 2–4: the skill must state the contract of the binary it ships with. On main that contract is version-relative and test-enforced. Fix this at the owning layer: rebase onto main and edit main's structure. Do not restore a hard-coded 0.13 snapshot.

Optional findings

5. repair and profile are public commands at this head (crates/omnigraph-cli/src/cli.rs), but no skill file names them now. The old SKILL.md named both. On main, the Command Index test would force them back.
6. The PR deletes the whole Common Gotchas table. Some rows are still true on main: init has no --json, enums are inline only (enum_type in schema.pest), and limit takes an integer literal. Keep the rows that are still true and remove only the version-history rows. The table maps error text to a fix, which agents use.
7. main moved the Gruber criteria and provenance guidance into references/schema-design.md (docs(skill): consolidate schema design guidance and add multi-agent principles #811). The rebased reference table must link that file. The PR body says "Keep all 13 skill reference filenames stable", but main now has 14, and crates/omnigraph-server/src/mcp.rs serves them by key as MCP resources.

What to keep (verified correct at this head and on main)

I checked these against the code at 2990fa3 and at main 4d7536d6. main's docs still have the old, wrong text, so these edits are worth landing:

• Live policy changes: preview_deployment_scope (crates/omnigraph-cluster/src/deployment/execution.rs) refuses only ResourceKind::Unknown, so live policy edits are allowed. main's docs/user/operations/policy.md and references/server-policy.md still say they are refused with deployment_scope.
• Graph-deletion permissions: graph deletion checks read and schema_apply on the graph, plus config_manage (crates/omnigraph-cluster/src/authorization.rs).
• Provider secrets: ${ENV} provider keys are resolved at startup and in deployment_settings_from_snapshot during a live deployment (crates/omnigraph-server/src/deployment.rs, settings.rs). main's docs/user/search/embeddings.md still says startup only.
• Plan route: POST /cluster/plan exists, but main's docs/user/operations/server.md route table still does not list it.
• Removed routes and flags: the routes /read, /change, /ingest and /graphs/{id}/schema/apply do not exist on main. Neither does the --schema-correction flag (cli_cluster_e2e.rs asserts "unexpected argument"). main's references/server-policy.md, schema.md and migrations.md still describe them.
• Identity credentials are accepted only at version == 2 (data_tokens.rs).

Tradeoffs and software liability

• Removed liability: about 1,100 net lines of duplicated or historical prose, and several false statements.
• Added liability: whole-file rewrites of the most-edited docs. Each rewrite conflicts with every docs PR open at the same time. Five more changes of this shape would serialize all skill and doc work behind them. The rewrite also deletes the sections main now uses as test-checked sources.
• Preferred shape: one small PR per contract on current main (policy live update, provider secrets, /cluster/plan, removed routes and flags), plus a separate trim. Fewer lines alone is not proof of a better result here.

Validation

Commit	Command	Result
2990fa3 (head)	python3 scripts/check-docs.py	pass (213 Markdown files)
2990fa3	bash scripts/check-agents-md.sh	pass
2990fa3	typos v1.50.1 (CI pin)	pass
main 4d7536d6	cargo test -p omnigraph-cli --locked --bin omnigraph skill::tests	5 passed, 0 failed
main 4d7536d6 + this PR's SKILL.md and references/commands.md (temporary overlay, reverted)	same command	2 passed, 3 failed: no ## Command Index section; no ## CLI Reference (condensed) section; SKILL.md must state internal-schema 16 (serves v14 to v16)
main 4d7536d6	git merge --no-commit 2990fa3 (aborted)	5 conflicted files, 13 hunks

Exact-commit CI: 24 checks pass and 5 are skipped. Azurite Azure Integration was cancelled at its 90-minute limit while it compiled, and the run concluded cancelled. The PR changes no Rust code, so that job gives no evidence either way. A rebase makes a new head, which needs a fresh full run. Do not waive the gate.

Regression proof: this PR is documentation only, with no engine change. No GQT or Rust regression applies to its prose fixes, so I checked them by code inspection only. The only executable contract for this content is the CLI skill guard on main, and the PR's content fails it (the overlay row in the table).

Limits: I did not run the full workspace tests or a cargo build at the head. I did not check every sentence in clusters/index.md, deployment.md, migrations.md or aliases.md against the code; I checked the claims listed here only. No performance claims are made.

[cursor]

Blocking (finding 3). docs/dev/documentation.md (Release notes) says "No PR number or release number is needed". This note says "the current 0.13 workflows", but it would ship in the 0.14 notes. Fix: describe the outcome without a version, for example: "The agent skill and deployment guides describe live configuration updates and exact receipts, and no longer list removed routes and flags."

[cursor]

Blocking (finding 4). This text was true at 0.13. On main it is false after #899 and #893.

main's docs/user/deployment.md now says: on local storage and S3, a clean server shutdown closes its storage scope, waits for accepted writes, and releases its own cluster admission. Azure still keeps the lock. A fresh S3 bootstrap can pass ownership to the first server with --bootstrap-handoff.

An agent that follows this text, or the force-unlock-before-serving step at line 99, would look for a lock that is no longer there. Fix: on rebase, state which writers keep admission: direct apply, direct writes, uncertain or interrupted shutdown, and Azure. Link deployment.md#writer-topology instead of restating the procedure. main's own cluster.md and server-policy.md still have the old sentence, so fix it there too.

[cursor]

Blocking (findings 2 and 3). On main 4d7536d6 this file fails two CLI guard tests in crates/omnigraph-cli/src/skill.rs:

• skill_condensed_reference_names_every_top_level_command panics with no ## CLI Reference (condensed) section. This rewrite deletes that section.
• skill_states_the_storage_formats_this_binary_reports panics with SKILL.md must state internal-schema 16 (serves v14 to v16). main now serves v14 to v16, not format 14 only.

main also ships a version-matched skill (omnigraph skill export / skill show). "Cover 0.13 only" is therefore the wrong shape. Fix: rebase onto main. Keep the ## CLI Reference (condensed) section and the exact omnigraph version storage line. Tell the reader to check omnigraph version instead of naming a release.

[cursor]

Blocking (finding 2). On main, skill_command_index_lists_every_public_command parses a ## Command Index table in this file. It requires the table to equal the clap tree's public command paths exactly. This rewrite has no such section, so the test panics with no ## Command Index section. This file also conflicts with main in 5 hunks.

Optional (finding 5). At this head, repair and profile are public commands (crates/omnigraph-cli/src/cli.rs), but no skill file names them now. Fix: rebase onto main's commands.md. Keep the Command Index, and apply only the factual corrections on top of it.

[cursor]

Optional (findings 6 and 7).

• main moved the schema-design guidance (Gruber criteria, provenance) into references/schema-design.md (docs(skill): consolidate schema design guidance and add multi-agent principles #811). main now has 14 references, and crates/omnigraph-server/src/mcp.rs serves them as MCP resources by key. On rebase, link schema-design.md in this table.
• This rewrite deletes the whole Common Gotchas table. Several rows are still true on main: init has no --json, enums are inline only (enum_type in schema.pest), and limit takes an integer literal. Agents use that table to map error text to a fix. Keep the rows that are still true and remove only the version-history rows.

[cursor]

Blocking (finding 4). "Even a clean exit retains the cluster lock" contradicts main after #899. There, a settled clean shutdown on local storage or S3 releases admission, and only Azure and unsettled exits keep it. This file also conflicts with main in 2 hunks. Fix: on rebase, keep main's shutdown-release paragraph and apply this PR's simplifications around it.

[cursor]

Blocking (finding 3). On main this line conflicts with "Normal open accepts storage formats v14 to v16". main also documents the stamp-v14-to-v16 route, which as commit, commit publish, commit drop and as unattached branch require. The route table below has no row for v14/v15 to v16. Fix: on rebase, build the table from main's format range. Name no release in the heading, or name the release the binary reports.

[ragnorc]

Review of 2990fa3 — recommendation: request changes

Rebase this branch onto current main, or re-cut the factual fixes as small edits on main. Do not merge this head.

This is a review comment. The recommendation is request changes.

Why, what, how, impact

• Why: The skill and the operator guides still describe removed routes, a removed flag, a false rule that policy edits are refused, and the wrong time for provider-secret resolution.
• What: This pull request rewrites 20 files (+812 / −1,900). It removes duplicate text and corrects those facts for the 0.13 release.
• How: It replaces whole files. The largest replacements are skills/omnigraph/SKILL.md, references/commands.md, references/cluster.md, references/migrations.md, and the deployment and cluster guides.
• Impact: Several corrections are still true on current main. The branch is based on v0.13.1 (8ca09c15). main is now 85a46138, 117 commits later. GitHub reports CONFLICTING. A trial merge conflicts in 7 files (19 hunks). One file has no conflict and would install storage instructions that this binary does not implement. The rewrite also deletes the sections the CLI tests read. Do not merge this head.

A review comment on this same head used main 4d7536d6. This comment checks the same head against main 85a46138.

Blocking findings

1. The branch does not merge, and one clean result is the wrong storage contract. A trial merge of 2990fa3 onto main 85a46138 conflicts in 7 files (19 hunks): skills/omnigraph/SKILL.md (3), references/commands.md (7), references/schema.md (1), docs/user/clusters/index.md (3), docs/user/deployment.md (2), docs/user/operations/policy.md (1), docs/user/operations/upgrade.md (2). main has edited 13 of the 20 files since 8ca09c15.

   skills/omnigraph/references/migrations.md is not one of those 13, so it merges with no conflict. The merged file is the pull request text: "the only served storage format is 14" and "0.13, whose only upgrade target is 14" (references/migrations.md lines 4 and 23). On main, INTERNAL_MANIFEST_SCHEMA_VERSION is 16 and MIN_SUPPORTED_INTERNAL_SCHEMA_VERSION is 14 (crates/omnigraph-catalog/src/migrations.rs). omnigraph upgrade --to-format accepts 16 only (crates/omnigraph/src/db/upgrade.rs). A conflict resolution will not catch this file.

   Open pull requests that edit the same guides: feat(server)!: assert the expected actor with Omnigraph-If-Actor #1074 and feat(server)!: say on every error body whether the request ran #1076 (SKILL.md, cluster.md, migrations.md, server-policy.md, remote-ops.md, and the cluster, deployment, policy, and server guides), feat(cli): serve a target for you on loopback #1083 (docs/user/clusters/index.md), fix(catalog): a publication that never sent its manifest is unpublished #1092 and fix(server): scope an unknown storage outcome to its key and branch #1096 (docs/user/deployment.md). feat(server)!: assert the expected actor with Omnigraph-If-Actor #1074 and feat(server)!: say on every error body whether the request ran #1076 also carry an HTTP-contract 0.14 change. feat(cli): bridge an agent's MCP over stdio to a target #1084, feat(cli)!: replace legacy routing with explicit targets #1090, rfc: standardize HTTP API conventions #1089, rfc: graph access and cross-process writes #1017, and rfc: storage outcomes per operation and restartable ownership #1093 do not edit these guides.

2. The rewrite removes the sections the CLI tests read. On main, crates/omnigraph-cli/src/skill.rs holds the skill to the clap tree (docs/dev/testing.md, omnigraph-skill). That is the one source of truth for command names and for the storage line omnigraph version prints. This head deletes the three sections those tests parse:

   • skill_command_index_lists_every_public_command reads ## Command Index in references/commands.md. This head's file starts at # Command Reference and has no such section.
   • skill_condensed_reference_names_every_top_level_command reads ## CLI Reference (condensed) in SKILL.md. This head has no such section.
   • skill_states_the_storage_formats_this_binary_reports requires the exact line `internal-schema 16 (serves v14 to v16)`. SKILL.md line 14 says "cover 0.13 only, serving storage format 14".

   On main 85a46138 those three strings are present. On this head they are absent. I checked the strings in the files. I did not compile the CLI (see Validation).

   Fix this at the owning layer. Rebase onto main. Keep the Command Index, the condensed CLI reference, and the exact omnigraph version storage line. Put the factual corrections on that structure. A hard-coded 0.13 snapshot cannot satisfy a test that reads the binary's own version line.

3. The storage and upgrade text is the 0.13 contract. This binary is not. main reports internal-schema 16 (serves v14 to v16) (skills/omnigraph/SKILL.md on main, and the constants above). docs/user/operations/upgrade.md on main says normal open accepts v14 to v16, and that v0.14 moves to Lance 13 with the full-text analyzer unchanged. This pull request says otherwise:

   • SKILL.md line 14: "cover 0.13 only, serving storage format 14".
   • docs/user/operations/upgrade.md line 3: "OmniGraph 0.13 opens storage format v14". The same file, lines 131–132, tells the operator to rebuild full-text indexes after a conversion because of the Lance 9/10 analyzer. On main that rebuild belongs to the v0.9-to-v0.10 transition. The Lance 13 bump does not change the analyzer (docs/dev/lance.md on main, "Full-text compatibility", and docs/user/operations/upgrade.md "Lance substrate upgrades").
   • changelog.d/current-agent-guides.changed.md says "the current 0.13 workflows". docs/dev/documentation.md says a release note needs no release number. This note would ship in the 0.14 notes.

   The HTTP contract value 0.13 still matches HTTP_API_CONTRACT on main (crates/omnigraph-api-types/src/lib.rs). The storage-format sentences do not. main also ships a version-matched skill (omnigraph skill export / skill show). Tell the reader to check omnigraph version. Do not name a release as the scope of the skill.

4. The writer-lock procedure is false for a settled clean shutdown on local storage and on S3. This head says a server keeps the cluster lock after every exit, including a clean exit, and it gives a force-unlock-before-serving procedure:

   • SKILL.md lines 24 and 55–58.
   • references/cluster.md lines 98–110. This file merges with no conflict.
   • references/server-policy.md lines 17–19. The clean merge keeps this sentence.
   • docs/user/deployment.md lines 81–83: "Even a clean exit retains the cluster lock." This file conflicts in 2 hunks.

   On main, after a settled clean shutdown, a non-Azure server closes its storage scope and calls release_after_settlement (crates/omnigraph-server/src/lib.rs, the shutdown path around the az:// branch). An az:// root keeps admission. Uncertain storage completion keeps admission and returns an error. docs/user/deployment.md on main already says this, and it documents --bootstrap-handoff for the first S3 server only.

   An agent that follows this head would run cluster force-unlock when a settled local or S3 server has already released the lock. On rebase, state which writers keep admission: direct apply, direct writes, uncertain or interrupted shutdown, and Azure. Link deployment.md for the shutdown cases. main's own references/cluster.md and references/server-policy.md still have the old sentence, so correct it in those files in the same change.

Optional findings

5. At this head, repair and profile are public commands (crates/omnigraph-cli/src/cli.rs) and no skill file names them. On main the Command Index test lists every public command, including later commands such as organization. Keep that index. Do not maintain a second command list by hand.

6. This head deletes the Common Gotchas table. Three rows are still true on main: init has no --json (InitArgs has schema, uri, and force only), enums are inline only (enum_type in schema.pest), and limit takes an integer (limit_clause in query.pest). Keep the rows that are still true. Remove only the rows that describe a retired release.

7. docs/user/operations/policy.md line 18 says schema_apply covers "Schema changes and graph deletion (also requires read)". Graph deletion does check read and schema_apply (authorize_graph_deletion in crates/omnigraph-cluster/src/deployment/execution.rs). A graph-delete plan change also takes the config_manage path (authorize_candidate in authorization.rs, the branch that sets needs_config). The table row omits config_manage. On rebase, keep main's action table, which already has commit_publish, commit_drop, and the explain load csv note, and name all three checks for deletion.

8. main has 14 skill references. This head has 13. The extra file is references/schema-design.md. The rebased reference table in SKILL.md should link it. The pull request body says "Keep all 13 skill reference filenames stable." That count is the 0.13 set.

Corrections that are still true

I checked these against the code at 2990fa3 and at main 85a46138. They are worth landing on top of main's current text:

• Live policy changes. preview_deployment_scope returns deployment_scope only for ResourceKind::Unknown (crates/omnigraph-cluster/src/deployment/execution.rs). Live policy edits are allowed. The opening of docs/user/operations/policy.md on main still says servers load policy at startup or when activating a new graph. A later section of that file already describes cluster apply --server. Keep the opening correction, and keep main's later section.
• Provider secrets. EmbeddingProviderConfig::resolve reads the ${NAME} variable from the process environment (crates/omnigraph-cluster/src/types.rs). settings_from_snapshot_inner calls it, and both startup and deployment_settings_from_snapshot use that function (crates/omnigraph-server/src/settings.rs). docs/user/search/embeddings.md on main still says resolution happens at startup and not at plan or apply. This pull request's paragraph merges cleanly and matches the code. It also says an update does not re-embed stored rows. I did not re-verify that second sentence in the embed pipeline.
• POST /cluster/plan. The route exists (crates/omnigraph-server/src/lib.rs). The route table in docs/user/operations/server.md on main does not list it. The added row merges cleanly.
• Removed routes and the removed flag. The server source on main has no /read, /change, /ingest, or /graphs/{id}/schema/apply route. The CLI has no --schema-correction flag. main's references/server-policy.md, references/schema.md, and references/migrations.md still describe them. Deleting those descriptions is right. schema.md conflicts, so resolve that file from main and then delete only the retired sentences.
• Identity credentials. A data token is accepted only when claims.version == 2 (crates/omnigraph-server/src/data_tokens.rs on both trees).

Tradeoffs and software liability

• Liability removed: about 1,100 net lines of duplicated or historical prose, and several false statements that main still carries (startup-only provider secrets, the missing /cluster/plan row, the removed routes and flag).
• Liability added: whole-file rewrites of the guides that other work edits at the same time. This head already conflicts with main and overlaps feat(server)!: assert the expected actor with Omnigraph-If-Actor #1074, feat(server)!: say on every error body whether the request ran #1076, feat(cli): serve a target for you on loopback #1083, fix(catalog): a publication that never sent its manifest is unpublished #1092, and fix(server): scope an unknown storage outcome to its key and branch #1096. Five more changes of this shape would make every skill and operator-guide change wait on a rewrite. The rewrite also deletes the sections main uses as the test-checked command list and storage line. A shorter file is not a smaller contract when the deleted lines are that source of truth.
• Preferred shape: rebase onto main. Keep the tested sections. Land the corrections listed above as edits to the current pages. State shutdown admission the way deployment.md on main states it. Describe the storage range the binary reports, with no release number in the changelog note. Split the trim from the factual fixes if the diff stays a whole-file replacement.

Validation

Commit	Command or check	Result
2990fa3	python3 scripts/check-docs.py (after pip install -r scripts/requirements-docs.txt)	pass, 213 Markdown files
2990fa3	bash scripts/check-agents-md.sh	pass, 52 links, 50 docs
85a46138 merge 2990fa3	git merge --no-commit --no-ff in a detached worktree, then git merge --abort	7 conflicted files, 19 hunks; migrations.md merged and states format 14 only
2990fa3 and 85a46138	string check of the three skill.rs predicates	main has ## Command Index, ## CLI Reference (condensed), and `internal-schema 16 (serves v14 to v16)`. This head has none of them
GitHub, this head	check rollup	24 checks succeeded, 5 skipped, Azurite Azure Integration cancelled. mergeable is CONFLICTING

Exact-commit CI: the succeeded checks ran on 2990fa3. Azurite Azure Integration was cancelled at its job limit while it compiled. The author note on this pull request says the same. This pull request changes no Rust code, so that job is not evidence of a test failure and not evidence of a pass. Do not waive it. A rebase is a new head and needs a new full run.

Regression proof: this pull request changes documentation only. It does not change query rows, counts, column types, or engine errors, so a .gqt case cannot express the defect. The executable contract for this content is the CLI skill guard on main. I did not run cargo test: a build of omnigraph-cli at 85a46138 pulls the Lance 13 workspace, and I did not compile it. The failure mode is the test source itself. Each test panics when its section or its exact storage line is absent, and those strings are absent at this head and present on main.

Limits: I did not run typos (the typos binary is not installed here; CI pins v1.50.1). I did not run the workspace tests or a cargo build. I did not check every sentence in docs/user/clusters/index.md, references/aliases.md, references/queries.md, or references/data.md. I checked the claims in this comment. No performance claim is made. The "does not re-embed stored rows" sentence in the embeddings edit was not traced through the embed pipeline.