docs(dev): ledger update — cross-repo drift status

[aaltshuler]

Follow-up to #293. Keeps the user-docs coherence ledger honest after the cross-repo work:

• omnigraph-cookbooks bearer_token_env chain — resolved by cookbooks PR Rewrite README around context-layer positioning #26 (deleted docs/best-practices.md in the 0.7 restructure; the stale chain survives nowhere on main).
• omnigraph-ts catalog mcp.expose description — documented why there's no hand-fix: the SDK's sync-spec.ts pulls openapi.json from a tagged omnigraph release, and the catalog fix (docs(user): coherence cleanup aligned with 0.7.1 #293) landed on main after the v0.7.1 tag, so it reaches the SDK on its next version bump (v0.7.2+), not via an out-of-band edit.

Docs-only.

🤖 Generated with Claude Code

Greptile Summary

This docs-only PR updates the internal dev coherence ledger with resolution status for the two cross-repo drift findings surfaced in the 0.7.1 sweep (#293). Both claims were verified against the related repos: docs/best-practices.md is confirmed absent from omnigraph-cookbooks, and scripts/sync-spec.ts in omnigraph-ts does indeed fetch openapi.json from a pinned git tag, making a hand-edit futile.

• omnigraph-ts stale spec — documents why no hand-fix is appropriate: sync-spec.ts overwrites spec/openapi.json from a tagged release on every run, so the fix will flow in naturally at v0.7.2+.
• omnigraph-cookbooks bearer_token_env — marks the item RESOLVED; docs/best-practices.md was deleted wholesale in the cookbooks 0.7 restructure (PR Rewrite README around context-layer positioning #26), confirming no stale content survives on main.

Confidence Score: 5/5

Docs-only change to a dev-internal ledger; no code, configuration, or public-facing content is modified.

Both cross-repo factual claims are accurate — the cookbooks file is confirmed deleted, and the omnigraph-ts sync mechanism matches the ledger's description. The two comments are minor organisational suggestions that do not affect correctness.

No files require special attention.

Important Files Changed

Filename	Overview
docs/dev/docs-issues.md	Docs-only ledger update: documents the no-hand-fix rationale for the omnigraph-ts stale spec (tag-pinned sync), and marks the cookbooks bearer_token_env entry RESOLVED. Both claims verified against the related repos.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["Cross-repo drift findings\n(docs/dev/docs-issues.md)"] --> B["omnigraph-ts stale\nspec/openapi.json"]
    A --> C["omnigraph-cookbooks\nbest-practices.md\nbearer_token_env chain"]

    B --> D{"How does SDK sync?"}
    D --> E["scripts/sync-spec.ts fetches\nomnigraph/v{version}/openapi.json\nfrom a git tag"]
    E --> F["Fix landed on main\nafter v0.7.1 tag"]
    F --> G["Hand-edit would be\noverwritten on next sync\nTracked, not actioned"]
    G --> H["Resolves automatically\nat SDK v0.7.2+"]

    C --> I{"File exists in\nomnigraph-cookbooks?"}
    I --> J["docs/best-practices.md\ndeleted in 0.7 restructure\n(cookbooks PR #26)"]
    J --> K["RESOLVED — stale chain\nsurvives nowhere on main"]

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A["Cross-repo drift findings\n(docs/dev/docs-issues.md)"] --> B["omnigraph-ts stale\nspec/openapi.json"]
    A --> C["omnigraph-cookbooks\nbest-practices.md\nbearer_token_env chain"]

    B --> D{"How does SDK sync?"}
    D --> E["scripts/sync-spec.ts fetches\nomnigraph/v{version}/openapi.json\nfrom a git tag"]
    E --> F["Fix landed on main\nafter v0.7.1 tag"]
    F --> G["Hand-edit would be\noverwritten on next sync\nTracked, not actioned"]
    G --> H["Resolves automatically\nat SDK v0.7.2+"]

    C --> I{"File exists in\nomnigraph-cookbooks?"}
    I --> J["docs/best-practices.md\ndeleted in 0.7 restructure\n(cookbooks PR #26)"]
    J --> K["RESOLVED — stale chain\nsurvives nowhere on main"]

Loading

_{Reviews (1): Last reviewed commit: "docs(dev): update coherence ledger — coo..." | Re-trigger Greptile}

Greptile also left 2 inline comments on this PR.

[greptile-apps]

RESOLVED item lives in the "Open" section

The section header reads "Open — surfaced 2026-06-20, not yet fixed", but the cookbooks entry is now annotated RESOLVED inline. A future auditor scanning for open work may skim past the inline tag and count it as an outstanding item, especially once the list grows. Consider either removing the resolved bullet entirely (the finding is already captured as a P2 row in the Resolved table above via the bearer_token_env fix), or moving it up into the table with a short "cookbooks docs/best-practices.md deleted (PR #26)" row so the "Open" section stays strictly unresolved items.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[greptile-apps]

The omnigraph-ts SDK's package.json currently pins omnigraph.serverVersion to "0.7.0", not "0.7.1". The ledger's "v0.7.2+" ceiling is still correct (the fix post-dates the v0.7.1 tag), but noting 0.7.0 as the current pin would make the lag explicit — a reader looking at the SDK today would see it is two minor versions behind, not one. See omnigraph-ts/package.json.

Suggested change

	`packages/sdk/src/generated/types.gen.ts` still describe the `GET /queries`
	catalog as the `mcp.expose` subset. **No hand-fix:** the SDK's
	`scripts/sync-spec.ts` pulls openapi.json from a *tagged* omnigraph release
	(`/omnigraph/v{version}/openapi.json`), and the catalog fix landed on main
	*after* the v0.7.1 tag — so it is in no tag yet and a hand-edit would be
	overwritten on the next sync. It flows in automatically when the SDK bumps
	to a tag containing the fix (v0.7.2+). Tracked, not actioned.
	`packages/sdk/src/generated/types.gen.ts` still describe the `GET /queries`
	catalog as the `mcp.expose` subset. **No hand-fix:** the SDK's
	`scripts/sync-spec.ts` pulls openapi.json from a *tagged* omnigraph release
	(`/omnigraph/v{version}/openapi.json`), and the catalog fix landed on main
	*after* the v0.7.1 tag — so it is in no tag yet and a hand-edit would be
	overwritten on the next sync. It flows in automatically when the SDK bumps
	to a tag containing the fix (v0.7.2+). SDK currently pins `serverVersion`
	`"0.7.0"` (two versions behind). Tracked, not actioned.