# 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

| Skill | Facts and behavior | Task routing | Public output |
|---|---|---|---|
| `dreamlake-notes` | Workspace `docs/pages/notes/+Page.mdx` | `docs/skill-guides/notes/SKILL.md` and `actions/*.md` | Action guides plus generated Notes references |
| `dreamlake-cli` | CLI repository `docs/pages/**/+Page.mdx` | CLI `docs/skill-guides/cli/SKILL.md` and `actions/*.md` | Action guides plus the full generated CLI reference |
| `dreamlake-scene-generation` | Workspace `docs/pages/{scene-generation,libraries,envs,envs/layers}/+Page.mdx` | `docs/skill-guides/scene-generation/SKILL.md`, `actions/*.md` and `tools/*.py` | Action guides and scene tools plus those four generated references |

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:

```bash
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:

```bash
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.