Workflow — Local Kristal to GitHub v10
The recommended workflow is two independent paths: a mutable reader synchronization path, and an immutable qualified publication path.
1. Author and build locally
python tools/kristal.py check <workspace>
python tools/kristal.py build-v9 <workspace>
python tools/kristal.py build-ai <workspace>
python tools/kristal.py read-surface <workspace> --require-ready
The Local Kit retains canon, evidence/source boundaries, v9 state and exact read-surface file selection. A separate pack-ai can produce a portable AI capsule if requested; build-v9 alone does not always generate the AI capsule.
2. Synchronize for AI/read access (mutable)
Kristal Manager inventories, validates and synchronizes the exact selected projection into kristals/<slug>/ within a public or private collection repository. It updates the derived kristals/index.json; it does not publish a Release or activate a channel.
3. Qualify and publish (immutable)
Use GitHub Bootstrap/Setup to prepare and reconcile node infrastructure. Its workflows qualify the pinned source commit, verify the v9 State Snapshot and publication bundle, publish a draft GitHub Release, verify the downloaded assets, and finalize only after the remote check succeeds. Activation, when configured, is another operation.
LOCAL KIT: check → build-v9 → build-ai/read-surface
MANAGER: Validate → Sync (derived reader projection)
GITHUB SETUP: qualify → immutable publish → optional activate
KRISTALDIAG: independent contract / release examination
KOMPILER: optional read/query/context; no canonical lifecycle
Critical safety checks
- Use an exact 40-character Framework SHA in managed workflows.
- Do not treat a Manager sync commit as publication.
- Do not treat GitHub visibility, a directory listing or validator PASS as epistemic authority.
- An unsupported feature or failed verification must be surfaced, not converted into success.
See Toolchain-v10, GitHub-Read-Surfaces-v10, Security-and-Confidentiality-v10.
Sources: Authoring Kit docs/15_GITHUB_AUTHORING_WORKFLOW.md, docs/20_TOOLCHAIN_INTEROP.md; Manager README.md; Bootstrap README.md.