flywheel-canon 0.2.0__tar.gz

flywheel_canon-0.2.0/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+## 0.2.0 - 2026-09-22
+
+- Publishes to PyPI as `flywheel-canon`. The bare name `canon` belongs to an
+  unrelated project, so the distribution carries the prefix while the console
+  script stays `canon`.
+- Adds an OIDC trusted-publishing release workflow with tag/version, artifact
+  digest, clean-venv entry-point resolution, and sdist-rebuild gates.
+- Adds run-lock concurrency control, and fixes POSIX run-lock descriptor release.
+- Adds doctor diagnostics, retention planning, replay checks, rescue handoff, and
+  an import review policy.
+- Hardens Canon source reads.
+
+## 0.1.0 — 2026-09-07
+
+First GitHub release for Canon.
+
+- Keeps the existing read-only MCP surface: `canon.status`, `canon.doctor`,
+  `canon.blocks`, `canon.render`, `canon.validate`, and `canon.check`.
+- Adds provider-neutral continuity preview and export from explicit
+  `records.jsonl` and `atoms.jsonl` inputs.
+- Exports Canon Markdown, capsule JSON, readiness JSON, or a three-file bundle
+  containing `CANON.md`, `canon.capsule.json`, and `readiness-probe.json`.
+- Records source-state hashes, artifact hashes, target tier, omissions, and
+  does-not-prove limits in the generated capsule outputs.
+- Uses confined bundle publication or fails closed. On Windows, the final bundle
+  directory rename is parent-handle-relative and leaf-only.
+
+Limits:
+
+- Canon does not import ChatGPT web conversations, Codex task databases, Claude
+  web history, Claude Code sessions, provider auth caches, or credentials.
+- The `codex-cli` and `claude-code` targets are native-advisory. App and web
+  targets remain guided until their hosts provide stronger startup evidence.
+- Bundle export proves the command's publication boundary, not immutability
+  after the command returns.
+- New bundle creation currently requires the supported Windows native backend.
+  Linux and macOS refuse new bundle creation without writing. Preview and stdout
+  exports remain available there.
+- Release downloads are distributed through GitHub. No PyPI publication claim
+  is made.

flywheel_canon-0.2.0/LICENSE

@@ -0,0 +1,110 @@
+# Functional Source License, Version 1.1, MIT Future License
+
+## Abbreviation
+
+FSL-1.1-MIT
+
+## Notice
+
+Copyright 2026 Zain Dana Harper
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the MIT license that is effective on the second anniversary of the date we make
+the Software available. On or after that date, you may use the Software under
+the MIT license, in which case the following will apply:
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

flywheel_canon-0.2.0/MANIFEST.in

@@ -0,0 +1,8 @@
+include CHANGELOG.md
+recursive-include docs/art *.json *.svg
+# Ship format specifications and implementation decisions, not historical audits.
+include project-docs/F*.md
+include project-docs/R*.md
+include project-docs/V*.md
+include project-docs/M*.md
+recursive-include tests/fixtures *

flywheel_canon-0.2.0/PKG-INFO

@@ -0,0 +1,204 @@
+Metadata-Version: 2.4
+Name: flywheel-canon
+Version: 0.2.0
+Summary: A provider-neutral memory-bank, personality container, and continuity capsule CLI.
+Author: HarperZ9
+License-Expression: LicenseRef-FSL-1.1-MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# canon
+
+One record for your memory bank and your personality, shared across every model
+and every tool.
+
+![canon: one memory record, rendered into every tool's own file. Own one region of the file. Leave every byte outside it alone.](docs/art/canon-header.svg)
+
+You keep the same working relationship whether you open Claude Code, Claude CLI,
+ChatGPT, Codex, or a web surface: the same authored voice, the same accumulated
+memory, the same decisions. Today that lives in a dozen files with a dozen
+shapes (`CLAUDE.md`, `AGENTS.md`, `SOUL.md`, `GEMINI.md`) plus per-tool memory
+stores that do not talk to each other. canon gives all of them one typed record
+to draw from and write back to, and renders each tool's file from that record.
+
+## What it does
+
+- **One envelope, five kinds.** An authored personality block, a raw or extracted
+  memory, a synthesized persona, a decision record, and a reference to an
+  external research artifact all share one record shape with a provenance
+  receipt on every entry.
+- **Two scopes that layer.** A `global` block is your default everywhere; a
+  `workspace` block with the same id overrides it where that workspace applies.
+  A render resolves the effective set for its target, current entries only.
+- **Deterministic by construction.** Ordering uses a clock-free ordinal, so a
+  rebuild from the same records is byte-identical. The wall clock is kept only
+  as a non-authoritative convenience.
+- **An assembly, not a rewrite.** canon aims at proven engines rather than
+  replacing them: a memory fact-engine, an authored-block store, and a
+  cross-provider transport. It adds the one record they share and the renderer
+  that projects each surface.
+
+## How one record becomes the file each tool reads
+
+![Eight stages taking one record to the file a tool reads: record, validate, layer, resolve, render, region, allow-list, write. Every entry is one envelope in one of five kinds: an authored personality block, an episodic memory, a synthesized persona, a decision record, and a reference to an external research artifact. The validator checks every field and refuses a record it cannot vouch for. A workspace block overrides a global block carrying the same id, and the resolve step keeps current entries only, ordered by a clock-free ordinal so a rebuild is byte-identical. The block set is rendered to text and spliced into the span between the canon begin and end markers, and every byte outside that span is preserved. The write allow-list holds four surfaces: a global and a workspace file for Claude Code, an AGENTS.md for Codex, and a workspace SOUL.md for Hermes. A path outside that list is refused, and so is a file with no canon region. Three outcomes: written inside the markers canon owns, a surface that drifted and needs a human, and a file canon declines to write at all.](docs/art/surface-lane.svg)
+
+canon writes four paths and no others, and inside those four it rewrites only
+the span between its own markers. A file with no canon region is left alone.
+
+## How a rendered file is checked back against the record
+
+![Eight stages checking a rendered file back against its record: read, extract, ingest, canonical, compare, drops, legs, verdict. The file is read as it sits on disk and the region between the canon markers is extracted byte exactly. The region text is ingested back into records, each reduced to one canonical form so the comparison is against a single shape rather than a formatting accident. The rendered form and the ingested form are compared field by field. Every field that failed to survive is classified against the losses that storage adapter declared in advance, and a loss nobody declared is a refusal. The aggregate check folds four legs: surface drift, the vault round-trip, the vault read symmetry, and the persona assessment. A leg whose seam is not wired reports nothing and does not affect the result. The verdict is one exit code, zero when every wired leg passed and one otherwise, and all four gate functions in the codebase share that signature so a build keys on them the same way. Three outcomes: the record survives the file, a declared drop that was named in advance, and a refusal that returns a nonzero code.](docs/art/verdict-lane.svg)
+
+A round-trip that loses a field passes only when the adapter declared that loss
+in advance. Anything else fails the gate rather than logging a warning.
+
+## What canon carries
+
+![A table of twelve rows: what canon carries, how many of it there are, and where each number is read from. Five record kinds share one envelope. Two scopes layer, workspace over global. Four surfaces sit on the write allow-list: a global and a workspace file for Claude Code, an AGENTS.md for Codex, and a workspace SOUL.md for Hermes. Four storage adapters implement the backend protocol, and five capability tokens describe what each one can carry. Sixteen schema pins name the seams that carry a version. The aggregate check folds four legs, and four gate functions share the same zero or one exit code. 111 source modules hold 19,731 lines, and 53 test files hold 1061 tests. Two surfaces named in the roadmap are absent from the catalog, a global SOUL.md and a GEMINI.md, so canon does not render them.](docs/art/record-table.svg)
+
+Every count is asserted against the module that defines it in
+`tests/test_repo_art.py`.
+
+## Status
+
+F0 is the record of record: the canonical schema, its validator, and the
+per-scope layering. F1 adds the storage seam: a `MemoryBackend` protocol with
+capability tokens and four adapters, among them a zero-drop SQLite reference and
+injected-handle adapters for a memory fact-engine and an authored-block store.
+R0 adds the block round-trip gate: a byte-exact region boundary inside a managed
+file, a record-to-text renderer and its inverse, and a go/no-go verdict that
+proves a block set round-trips to its canonical form with every dropped field
+declared.
+
+R1 renders your files from the record. It resolves the block set for a file's
+scope and rewrites only the region canon owns, every byte outside it preserved.
+It writes only a fixed allow-list of files, and only a file you have opted in
+with a canon region. Where a tool reads both a global and a workspace file, the
+workspace file carries just your workspace blocks, so a shared block is never
+duplicated; where a tool reads one file, that file carries the full resolved set.
+
+R2 mirrors your whole record set into an Obsidian vault. Each record becomes one
+markdown note you can read, search, and link, and a MEMORY.md index lists them
+all. The full record rides inside every note, so a rebuild is exact and editing a
+note's prose never rewrites the record behind it. canon writes only inside its own
+vault, never touches a file it did not write, and when you drop a record it
+reports the note left behind rather than deleting it. R2 also adds SOUL.md to the
+rendered surfaces.
+
+V2 through V4 add the checks and the decision on top of them. A drift check
+re-derives every managed surface and compares only the region canon owns, so
+your own prose outside the markers is never flagged. A persona check reports
+whether the memories behind a synthesized persona still resolve. V4 separates a
+mechanical fast-forward from a conflict, writes the fast-forwards, and raises a
+durable gate for anything a human should adjudicate.
+
+A harness reaches all of this over MCP. `canon mcp` serves six read-only tools:
+identity, a readiness diagnostic, the authored record set, the render for a
+scope, the validator, and the aggregate check. Nothing on that server writes a
+file. Reconcile stays a library call, because rewriting your instruction files
+and raising a gate is an action with a person behind it.
+
+The CLI can also compile a provider-neutral continuity capsule from two explicit
+inputs: `records.jsonl` and `atoms.jsonl`. Preview reports artifact names,
+target tier, readiness probe data, and source-state hashes without writing.
+Export writes the same capsule as Canon Markdown, capsule JSON, readiness JSON,
+or a three-file bundle. The capsule records omitted state as typed atoms or
+transform omissions and says what the export does not prove, including host
+enforcement. It does not import provider auth, private databases, ChatGPT web
+state, or Claude web state.
+
+Installing a region into a fresh file, the first migrator on the version seam,
+and the global SOUL.md and GEMINI.md surfaces are later phases. Everything
+shipped is proven by a full test suite and aims at the one envelope.
+
+## Run it
+
+Canon 0.1.0 is prepared as a GitHub release candidate. Install from a reviewed
+GitHub release asset after publication, or from a local wheel during review:
+
+```bash
+python -m pip install canon-0.1.0-py3-none-any.whl
+```
+
+No PyPI package ownership or publication is claimed here.
+
+Serve the record set to a harness:
+
+```bash
+canon mcp
+```
+
+Ask canon what it believes, with no transport in the way:
+
+```bash
+canon check
+canon blocks
+```
+
+`canon check` exits non-zero when a wired leg fails or the block pool is not the
+authored set, so a build can key on it. Point it at your records with
+`CANON_BLOCKS_DIR`, and at your files with `CANON_HOME` and `CANON_WORKSPACE`.
+
+Preview and export a continuity capsule from explicit local inputs:
+
+```bash
+canon --json preview --workspace . --records records.jsonl --atoms atoms.jsonl --target codex-cli
+canon export --workspace . --records records.jsonl --atoms atoms.jsonl --target codex-cli --format canon-md
+canon export --workspace . --records records.jsonl --atoms atoms.jsonl --target codex-cli --format capsule-json
+canon --json export --workspace . --records records.jsonl --atoms atoms.jsonl --target codex-cli --format bundle --out bundle
+```
+
+The `codex-cli` and `claude-code` targets are native-advisory surfaces. App and
+web targets remain guided until their hosts provide stronger startup evidence.
+Preview and stdout exports work across supported Python platforms. Creating a
+new bundle currently requires Windows with the confined native writer. On Linux
+and macOS, new bundle creation returns `unsafe_path` without writing; use stdout
+export there. The Windows final directory rename is parent-handle-relative and
+leaf-only. This bounds publication, not immutability after the command returns.
+
+Run the suite:
+
+```bash
+python -m pytest
+```
+
+No runtime dependencies. Python 3.11 or newer.
+
+## Layout
+
+```
+src/canon/
+  schema.py, validator.py, layering.py   the record, its rules, per-scope resolve
+  backends/                              the storage seam and four adapters
+  region.py, textblock.py, fidelity.py   the byte boundary, the text codec, the gate
+  surface.py, registry.py                the render composition, the write allow-list
+  frontmatter.py, vault.py               the note frontmatter codec, the one-record note
+  vault_mirror.py, vault_fidelity.py     the whole-vault mirror and its round-trip gate
+  drift.py, writing_gate.py              the surface drift check, the injected prose gate
+  persona_thesis.py, canon_check.py      the persona basis adapter, the aggregate check
+  reconcile*.py                          the fast-forward decision and its durable gate
+  blocks.py, local_mcp.py, cli.py        the authored-block loader, the MCP door, the CLI
+  capsule*.py, atom.py, adapter.py       the continuity capsule, atom and target contract
+  cli_compile.py, cli_export.py          preview, stdout export and bundle export
+  cli_artifacts.py, cli_publish.py       source hashes and confined artifact publishing
+tests/                                   round-trip, validator, layering, backend,
+                                         fidelity, surface, orchestration, vault,
+                                         drift, reconcile, continuity, and artwork proofs
+docs/art/                                the drawings above and the spec they render from
+project-docs/                            the F0, F1, R0, R1, R2, V2, V3, V4, MCP decisions
+```
+
+See `project-docs/` for the schema reference, the layering derivation, the
+section-ownership contract, the declared drops each storage backend must
+announce, and the decisions behind the round-trip, vault, drift and reconcile
+gates.
+
+## License
+
+FSL-1.1-MIT. Functional Source License, source-available now for any purpose
+other than a competing product, and it converts to the MIT license two years
+after each version is released. See `LICENSE`.

flywheel_canon-0.2.0/README.md

@@ -0,0 +1,191 @@
+# canon
+
+One record for your memory bank and your personality, shared across every model
+and every tool.
+
+![canon: one memory record, rendered into every tool's own file. Own one region of the file. Leave every byte outside it alone.](docs/art/canon-header.svg)
+
+You keep the same working relationship whether you open Claude Code, Claude CLI,
+ChatGPT, Codex, or a web surface: the same authored voice, the same accumulated
+memory, the same decisions. Today that lives in a dozen files with a dozen
+shapes (`CLAUDE.md`, `AGENTS.md`, `SOUL.md`, `GEMINI.md`) plus per-tool memory
+stores that do not talk to each other. canon gives all of them one typed record
+to draw from and write back to, and renders each tool's file from that record.
+
+## What it does
+
+- **One envelope, five kinds.** An authored personality block, a raw or extracted
+  memory, a synthesized persona, a decision record, and a reference to an
+  external research artifact all share one record shape with a provenance
+  receipt on every entry.
+- **Two scopes that layer.** A `global` block is your default everywhere; a
+  `workspace` block with the same id overrides it where that workspace applies.
+  A render resolves the effective set for its target, current entries only.
+- **Deterministic by construction.** Ordering uses a clock-free ordinal, so a
+  rebuild from the same records is byte-identical. The wall clock is kept only
+  as a non-authoritative convenience.
+- **An assembly, not a rewrite.** canon aims at proven engines rather than
+  replacing them: a memory fact-engine, an authored-block store, and a
+  cross-provider transport. It adds the one record they share and the renderer
+  that projects each surface.
+
+## How one record becomes the file each tool reads
+
+![Eight stages taking one record to the file a tool reads: record, validate, layer, resolve, render, region, allow-list, write. Every entry is one envelope in one of five kinds: an authored personality block, an episodic memory, a synthesized persona, a decision record, and a reference to an external research artifact. The validator checks every field and refuses a record it cannot vouch for. A workspace block overrides a global block carrying the same id, and the resolve step keeps current entries only, ordered by a clock-free ordinal so a rebuild is byte-identical. The block set is rendered to text and spliced into the span between the canon begin and end markers, and every byte outside that span is preserved. The write allow-list holds four surfaces: a global and a workspace file for Claude Code, an AGENTS.md for Codex, and a workspace SOUL.md for Hermes. A path outside that list is refused, and so is a file with no canon region. Three outcomes: written inside the markers canon owns, a surface that drifted and needs a human, and a file canon declines to write at all.](docs/art/surface-lane.svg)
+
+canon writes four paths and no others, and inside those four it rewrites only
+the span between its own markers. A file with no canon region is left alone.
+
+## How a rendered file is checked back against the record
+
+![Eight stages checking a rendered file back against its record: read, extract, ingest, canonical, compare, drops, legs, verdict. The file is read as it sits on disk and the region between the canon markers is extracted byte exactly. The region text is ingested back into records, each reduced to one canonical form so the comparison is against a single shape rather than a formatting accident. The rendered form and the ingested form are compared field by field. Every field that failed to survive is classified against the losses that storage adapter declared in advance, and a loss nobody declared is a refusal. The aggregate check folds four legs: surface drift, the vault round-trip, the vault read symmetry, and the persona assessment. A leg whose seam is not wired reports nothing and does not affect the result. The verdict is one exit code, zero when every wired leg passed and one otherwise, and all four gate functions in the codebase share that signature so a build keys on them the same way. Three outcomes: the record survives the file, a declared drop that was named in advance, and a refusal that returns a nonzero code.](docs/art/verdict-lane.svg)
+
+A round-trip that loses a field passes only when the adapter declared that loss
+in advance. Anything else fails the gate rather than logging a warning.
+
+## What canon carries
+
+![A table of twelve rows: what canon carries, how many of it there are, and where each number is read from. Five record kinds share one envelope. Two scopes layer, workspace over global. Four surfaces sit on the write allow-list: a global and a workspace file for Claude Code, an AGENTS.md for Codex, and a workspace SOUL.md for Hermes. Four storage adapters implement the backend protocol, and five capability tokens describe what each one can carry. Sixteen schema pins name the seams that carry a version. The aggregate check folds four legs, and four gate functions share the same zero or one exit code. 111 source modules hold 19,731 lines, and 53 test files hold 1061 tests. Two surfaces named in the roadmap are absent from the catalog, a global SOUL.md and a GEMINI.md, so canon does not render them.](docs/art/record-table.svg)
+
+Every count is asserted against the module that defines it in
+`tests/test_repo_art.py`.
+
+## Status
+
+F0 is the record of record: the canonical schema, its validator, and the
+per-scope layering. F1 adds the storage seam: a `MemoryBackend` protocol with
+capability tokens and four adapters, among them a zero-drop SQLite reference and
+injected-handle adapters for a memory fact-engine and an authored-block store.
+R0 adds the block round-trip gate: a byte-exact region boundary inside a managed
+file, a record-to-text renderer and its inverse, and a go/no-go verdict that
+proves a block set round-trips to its canonical form with every dropped field
+declared.
+
+R1 renders your files from the record. It resolves the block set for a file's
+scope and rewrites only the region canon owns, every byte outside it preserved.
+It writes only a fixed allow-list of files, and only a file you have opted in
+with a canon region. Where a tool reads both a global and a workspace file, the
+workspace file carries just your workspace blocks, so a shared block is never
+duplicated; where a tool reads one file, that file carries the full resolved set.
+
+R2 mirrors your whole record set into an Obsidian vault. Each record becomes one
+markdown note you can read, search, and link, and a MEMORY.md index lists them
+all. The full record rides inside every note, so a rebuild is exact and editing a
+note's prose never rewrites the record behind it. canon writes only inside its own
+vault, never touches a file it did not write, and when you drop a record it
+reports the note left behind rather than deleting it. R2 also adds SOUL.md to the
+rendered surfaces.
+
+V2 through V4 add the checks and the decision on top of them. A drift check
+re-derives every managed surface and compares only the region canon owns, so
+your own prose outside the markers is never flagged. A persona check reports
+whether the memories behind a synthesized persona still resolve. V4 separates a
+mechanical fast-forward from a conflict, writes the fast-forwards, and raises a
+durable gate for anything a human should adjudicate.
+
+A harness reaches all of this over MCP. `canon mcp` serves six read-only tools:
+identity, a readiness diagnostic, the authored record set, the render for a
+scope, the validator, and the aggregate check. Nothing on that server writes a
+file. Reconcile stays a library call, because rewriting your instruction files
+and raising a gate is an action with a person behind it.
+
+The CLI can also compile a provider-neutral continuity capsule from two explicit
+inputs: `records.jsonl` and `atoms.jsonl`. Preview reports artifact names,
+target tier, readiness probe data, and source-state hashes without writing.
+Export writes the same capsule as Canon Markdown, capsule JSON, readiness JSON,
+or a three-file bundle. The capsule records omitted state as typed atoms or
+transform omissions and says what the export does not prove, including host
+enforcement. It does not import provider auth, private databases, ChatGPT web
+state, or Claude web state.
+
+Installing a region into a fresh file, the first migrator on the version seam,
+and the global SOUL.md and GEMINI.md surfaces are later phases. Everything
+shipped is proven by a full test suite and aims at the one envelope.
+
+## Run it
+
+Canon 0.1.0 is prepared as a GitHub release candidate. Install from a reviewed
+GitHub release asset after publication, or from a local wheel during review:
+
+```bash
+python -m pip install canon-0.1.0-py3-none-any.whl
+```
+
+No PyPI package ownership or publication is claimed here.
+
+Serve the record set to a harness:
+
+```bash
+canon mcp
+```
+
+Ask canon what it believes, with no transport in the way:
+
+```bash
+canon check
+canon blocks
+```
+
+`canon check` exits non-zero when a wired leg fails or the block pool is not the
+authored set, so a build can key on it. Point it at your records with
+`CANON_BLOCKS_DIR`, and at your files with `CANON_HOME` and `CANON_WORKSPACE`.
+
+Preview and export a continuity capsule from explicit local inputs:
+
+```bash
+canon --json preview --workspace . --records records.jsonl --atoms atoms.jsonl --target codex-cli
+canon export --workspace . --records records.jsonl --atoms atoms.jsonl --target codex-cli --format canon-md
+canon export --workspace . --records records.jsonl --atoms atoms.jsonl --target codex-cli --format capsule-json
+canon --json export --workspace . --records records.jsonl --atoms atoms.jsonl --target codex-cli --format bundle --out bundle
+```
+
+The `codex-cli` and `claude-code` targets are native-advisory surfaces. App and
+web targets remain guided until their hosts provide stronger startup evidence.
+Preview and stdout exports work across supported Python platforms. Creating a
+new bundle currently requires Windows with the confined native writer. On Linux
+and macOS, new bundle creation returns `unsafe_path` without writing; use stdout
+export there. The Windows final directory rename is parent-handle-relative and
+leaf-only. This bounds publication, not immutability after the command returns.
+
+Run the suite:
+
+```bash
+python -m pytest
+```
+
+No runtime dependencies. Python 3.11 or newer.
+
+## Layout
+
+```
+src/canon/
+  schema.py, validator.py, layering.py   the record, its rules, per-scope resolve
+  backends/                              the storage seam and four adapters
+  region.py, textblock.py, fidelity.py   the byte boundary, the text codec, the gate
+  surface.py, registry.py                the render composition, the write allow-list
+  frontmatter.py, vault.py               the note frontmatter codec, the one-record note
+  vault_mirror.py, vault_fidelity.py     the whole-vault mirror and its round-trip gate
+  drift.py, writing_gate.py              the surface drift check, the injected prose gate
+  persona_thesis.py, canon_check.py      the persona basis adapter, the aggregate check
+  reconcile*.py                          the fast-forward decision and its durable gate
+  blocks.py, local_mcp.py, cli.py        the authored-block loader, the MCP door, the CLI
+  capsule*.py, atom.py, adapter.py       the continuity capsule, atom and target contract
+  cli_compile.py, cli_export.py          preview, stdout export and bundle export
+  cli_artifacts.py, cli_publish.py       source hashes and confined artifact publishing
+tests/                                   round-trip, validator, layering, backend,
+                                         fidelity, surface, orchestration, vault,
+                                         drift, reconcile, continuity, and artwork proofs
+docs/art/                                the drawings above and the spec they render from
+project-docs/                            the F0, F1, R0, R1, R2, V2, V3, V4, MCP decisions
+```
+
+See `project-docs/` for the schema reference, the layering derivation, the
+section-ownership contract, the declared drops each storage backend must
+announce, and the decisions behind the round-trip, vault, drift and reconcile
+gates.
+
+## License
+
+FSL-1.1-MIT. Functional Source License, source-available now for any purpose
+other than a competing product, and it converts to the MIT license two years
+after each version is released. See `LICENSE`.