Docs to skills

Maintain the instructions people review in docs. Public skills distribute those instructions to agents. A correction starts in the owning guide; it must not become an independent edit to a generated skill.

Sources

Docs remain authoritative for product behavior, API facts and runnable examples. Action guides are separately authored routing and task procedures; keep them short, concrete and scoped to one operation. They may select useful details from docs but must not become another API manual. Entrypoints name the CLI as the default interface and route to independent action files. Keep Python guidance in a separate SDK integration skill only where documented APIs warrant one; do not mix SDK and CLI steps into one automatic route.

The Notes bundle keeps its generated Notes page for reference, plus focused read, edit, collaboration and attachment actions. The CLI bundle keeps its complete generated reference corpus and adds task-first actions. The scene-generation bundle also ships runnable helpers: everything under the guide's tools/ (the scripts and their pytest suite) is copied into the skill and hashed as guide source, so a tool fix follows the same docs-commit-then-sync path as a procedure fix. Only these three generated cores are covered by this pipeline; other public skills remain explicitly reviewed against their affected docs.

The public skills repo's sources.json records the source repository, commit and generator hash. generated-files.json records the exact files owned by the synchronizer. Other public skills are not yet migrated to this flow; their owners must still reconcile affected docs and skill content explicitly.

Update and check

Commit the reviewed source changes on a feature branch. From a checkout of dreamlake-skills, with access to the two source repositories:

python3 scripts/sync-docs.py --workspace /path/to/dreamlake-workspace --cli /path/to/dreamlake-cli
python3 scripts/sync-docs.py --workspace /path/to/dreamlake-workspace --cli /path/to/dreamlake-cli --check

The script reads committed HEAD snapshots, including docs pages, generators, the workspace's docs/skill-guides/{notes,scene-generation}/ (the scene-generation guide includes its tools/ — scripts and their test suite are hashed and shipped as guide source) and the CLI's docs/skill-guides/cli/, then runs each repository's generator in a temporary directory. sources.json records commits, generator hashes, every guide-file hash, the Notes source-page hash, and the hashes of the four scene reference pages it bundles (scenePages: scene-generation, libraries, envs, envs/layers); generated-files.json records the exact skill outputs owned by sync. Review that file list before publication. Sync does not modify source checkouts, publish docs, install skills or remove unrelated resources. Node and Git are required; generation needs no credentials.

To reproduce the recorded release instead of checking current source heads:

python3 scripts/sync-docs.py --workspace /path/to/dreamlake-workspace --cli /path/to/dreamlake-cli --check --locked

Use --check against current source heads to detect propagation gaps. --locked proves reproducibility of the recorded source only; it cannot prove that newer docs have propagated. Publish accessible companion source branches before asking a teammate to reproduce unpublished commits.

Verification and release

• Inventory user tasks and split CLI and SDK requests into distinct entrypoints where both interfaces are supported. Put each frequent operation in its own action file; preserve setup, exact commands, revision rules, capability/version limits and failure handling. Link the full reference only when a step needs detail. Never summarize away required API operations or CodeTabs examples.
• Evaluate independent requests: representative tasks for every action (Notes read, edit, watch, attachments; CLI setup, data, Notes, artifact, workflow) and boundaries for SDK-only requests, unreleased flags, stale revisions and paths containing spaces. Confirm the right interface and action, safe failure response and selective reference lookup. Revise source docs or guides when an evaluation exposes a gap.
• Commit source docs, action guides and generators. Run each generator and its --check, sync public outputs and review the generated diff plus source map. Run public offline sync tests and --verify-files. Full sync --check against current heads detects drift; --locked reproduces recorded source, while --verify-files checks local integrity only.
• Link the source docs PR and skills PR. Deploy docs, publish skills, then compare live Markdown and a fresh skill install/download with the reviewed output. Report each stage separately; source sync and merge do not prove publication or installed readback.

Keep private operational material out of public exports. Review the generated file list before publishing. The workspace AGENTS.md states this policy; CLAUDE.md points to it.