softschema 0.2.0__tar.gz → 0.2.2__tar.gz

{softschema-0.2.0 → softschema-0.2.2}/AGENTS.md

@@ -7,7 +7,7 @@ Start here:
 - [softschema Guide](docs/softschema-guide.md): standalone concept and adoption guide
   for humans and agents.
 - [softschema Spec](docs/softschema-spec.md): exact language-neutral artifact format.
-- [Movie page example](examples/movie_page/README.md): complete Python-backed example.
+- [Movie Page Example](examples/movie_page/README.md): complete Python-backed example.
 
 softschema ships two interchangeable implementations with the same CLI and library
 surface: Python/Pydantic (`softschema`, `softschema-py`) and TypeScript/Zod

{softschema-0.2.0 → softschema-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: softschema
-Version: 0.2.0
+Version: 0.2.2
 Summary: Soft schema conventions and validation tools for Markdown/YAML artifacts
 Project-URL: Homepage, https://github.com/jlevy/softschema
 Project-URL: Repository, https://github.com/jlevy/softschema
@@ -29,12 +29,12 @@ Description-Content-Type: text/markdown
 # softschema
 
 Soft schemas: gradual, practical validation for Markdown/YAML artifacts that mix prose
-and structured data — built for humans and coding agents.
+and structured data—built for humans and coding agents.
 
 ## Quick Start
 
 Try it anywhere, with nothing installed but [uv](https://docs.astral.sh/uv/) or Node.
-Print the bundled example artifact and its compiled schema, then validate — the artifact
+Print the bundled example artifact and its compiled schema, then validate—the artifact
 is fully self-describing, so no flags are needed:
 
 ```bash
@@ -63,7 +63,7 @@ flexible document context and machine-readable values.
 The idea is quite simple, but I’ve found it non-obvious enough that coding agents do not
 come up with this approach themselves.
 
-However if given the information and tools in this repo, soft schemas are unreasonably
+However, if given the information and tools in this repo, soft schemas are unreasonably
 effective. Agents become far better at designing and building complex workflows that mix
 structured and unstructured data, such as document processing, data extraction,
 scientific or financial analyses, and many similar applications.
@@ -203,8 +203,8 @@ flags.
 
 Every key after `contract` is optional; a minimal artifact carries `contract` alone and
 binds its schema some other way (a `--schema` flag, or a host registry in library use).
-Contract IDs follow an enforced shape, `[namespace:]Name[/version]` — for example
-`example.movies:MoviePage/v1` or `com.acme.docs:IncidentReview/1.0` — naming a payload
+Contract IDs follow an enforced shape, `[namespace:]Name[/version]`—for example
+`example.movies:MoviePage/v1` or `com.acme.docs:IncidentReview/1.0`—naming a payload
 contract, not a class or import path.
 
 ## Validate
@@ -220,7 +220,7 @@ softschema validate doc.md --envelope incident          # designate the payload
 
 `validate` reports structural (JSON Schema) and semantic (Pydantic/Zod model) results
 separately as deterministic JSON. Semantic validation loads a model with
-`--model module:Class` (Python) or `--model path:export` (Zod) — note that `--model`
+`--model module:Class` (Python) or `--model path:export` (Zod)—note that `--model`
 imports and executes local code, so use it only with trusted models; a compiled schema
 via `--schema` executes nothing and is the safe path for untrusted input.
 
@@ -232,8 +232,8 @@ Two supported ways to consume softschema; pick by use:
   fast, offline, and the only way to `import` it):
 
   ```bash
-  uv add --dev softschema==0.2.0        # Python
-  npm install -D softschema@0.2.0       # Node (or: bun add -d)
+  uv add --dev softschema==0.2.2        # Python
+  npm install -D softschema@0.2.2       # Node (or: bun add -d)
   ```
 
 - **Zero-install** for one-off checks and agent bootstrap:
@@ -243,10 +243,9 @@ Two supported ways to consume softschema; pick by use:
   npx softschema@latest --help
   ```
 
-The rule of thumb: if softschema runs more than once, or in CI, or you import it — pin
-it. For a quick check or an agent bootstrapping with nothing installed, use a
-zero-install runner.
-See [Installation](docs/installation.md) for details, including the supply-chain
+The rule of thumb: if softschema runs more than once, or in CI, or you import it—pin it.
+For a quick check or an agent bootstrapping with nothing installed, use a zero-install
+runner. See [Installation](docs/installation.md) for details, including the supply-chain
 cool-off that makes `@latest` safe to recommend.
 
 ## Use as a Library

{softschema-0.2.0 → softschema-0.2.2}/README.md

@@ -1,12 +1,12 @@
 # softschema
 
 Soft schemas: gradual, practical validation for Markdown/YAML artifacts that mix prose
-and structured data — built for humans and coding agents.
+and structured data—built for humans and coding agents.
 
 ## Quick Start
 
 Try it anywhere, with nothing installed but [uv](https://docs.astral.sh/uv/) or Node.
-Print the bundled example artifact and its compiled schema, then validate — the artifact
+Print the bundled example artifact and its compiled schema, then validate—the artifact
 is fully self-describing, so no flags are needed:
 
 ```bash
@@ -35,7 +35,7 @@ flexible document context and machine-readable values.
 The idea is quite simple, but I’ve found it non-obvious enough that coding agents do not
 come up with this approach themselves.
 
-However if given the information and tools in this repo, soft schemas are unreasonably
+However, if given the information and tools in this repo, soft schemas are unreasonably
 effective. Agents become far better at designing and building complex workflows that mix
 structured and unstructured data, such as document processing, data extraction,
 scientific or financial analyses, and many similar applications.
@@ -175,8 +175,8 @@ flags.
 
 Every key after `contract` is optional; a minimal artifact carries `contract` alone and
 binds its schema some other way (a `--schema` flag, or a host registry in library use).
-Contract IDs follow an enforced shape, `[namespace:]Name[/version]` — for example
-`example.movies:MoviePage/v1` or `com.acme.docs:IncidentReview/1.0` — naming a payload
+Contract IDs follow an enforced shape, `[namespace:]Name[/version]`—for example
+`example.movies:MoviePage/v1` or `com.acme.docs:IncidentReview/1.0`—naming a payload
 contract, not a class or import path.
 
 ## Validate
@@ -192,7 +192,7 @@ softschema validate doc.md --envelope incident          # designate the payload
 
 `validate` reports structural (JSON Schema) and semantic (Pydantic/Zod model) results
 separately as deterministic JSON. Semantic validation loads a model with
-`--model module:Class` (Python) or `--model path:export` (Zod) — note that `--model`
+`--model module:Class` (Python) or `--model path:export` (Zod)—note that `--model`
 imports and executes local code, so use it only with trusted models; a compiled schema
 via `--schema` executes nothing and is the safe path for untrusted input.
 
@@ -204,8 +204,8 @@ Two supported ways to consume softschema; pick by use:
   fast, offline, and the only way to `import` it):
 
   ```bash
-  uv add --dev softschema==0.2.0        # Python
-  npm install -D softschema@0.2.0       # Node (or: bun add -d)
+  uv add --dev softschema==0.2.2        # Python
+  npm install -D softschema@0.2.2       # Node (or: bun add -d)
   ```
 
 - **Zero-install** for one-off checks and agent bootstrap:
@@ -215,10 +215,9 @@ Two supported ways to consume softschema; pick by use:
   npx softschema@latest --help
   ```
 
-The rule of thumb: if softschema runs more than once, or in CI, or you import it — pin
-it. For a quick check or an agent bootstrapping with nothing installed, use a
-zero-install runner.
-See [Installation](docs/installation.md) for details, including the supply-chain
+The rule of thumb: if softschema runs more than once, or in CI, or you import it—pin it.
+For a quick check or an agent bootstrapping with nothing installed, use a zero-install
+runner. See [Installation](docs/installation.md) for details, including the supply-chain
 cool-off that makes `@latest` safe to recommend.
 
 ## Use as a Library

{softschema-0.2.0 → softschema-0.2.2}/docs/development.md

@@ -1,10 +1,9 @@
 # Development
 
 First-time setup of `uv` and Python is covered in [Installation](installation.md).
-Release workflow and PyPI steps are covered in
-[Publishing](https://github.com/jlevy/softschema/blob/main/docs/publishing.md).
-The full validation pass — the automated sweep run locally plus the manual
-clean-environment checks CI cannot run — is codified in the
+Release workflow and PyPI steps are covered in [Publishing](publishing.md).
+The full validation pass—the automated sweep run locally plus the manual
+clean-environment checks CI cannot run—is codified in the
 [end-to-end testing runbook](e2e-testing.runbook.md).
 
 Set up the repo (Python deps, Node tooling for hooks, and the git hooks themselves):
@@ -39,7 +38,7 @@ uv build
 
 The Python package is built from `packages/python/src/softschema`.
 
-### Git hooks (this repo)
+### Git Hooks (This Repo)
 
 Hooks are managed by [lefthook](https://lefthook.dev) (`lefthook.yml`), installed with
 `make hooks-install`. The `pre-commit` hook formats staged changes so commits stay
@@ -69,8 +68,7 @@ bun run publint     # lint the publishable package layout (run after build)
 
 It publishes to npm as `softschema` (the same name as the PyPI package) and exposes the
 CLI as both `softschema` and `softschema-ts`. The two packages **release together under
-one version number**; see
-[Publishing](https://github.com/jlevy/softschema/blob/main/docs/publishing.md).
+one version number**; see [Publishing](publishing.md).
 
 Documentation changes should follow `common-doc-guidelines.md`
 (github.com/jlevy/practical-prose).
@@ -81,7 +79,7 @@ exact format rules in `docs/softschema-spec.md`.
 
 Two softschema checks belong in CI for any project that depends on the package.
 
-### Compiled schema drift
+### Compiled Schema Drift
 
 A committed `.schema.yaml` file is *generated, but committed*. Run
 `softschema compile ... --check` to fail the build when the committed compiled schema
@@ -96,10 +94,10 @@ uv run softschema compile examples.movie_page.model:MoviePage \
 Fix on drift: re-run the same command without `--check` and commit the regenerated
 compiled schema.
 
-### Generated-section drift
+### Generated-Section Drift
 
 If any Markdown file contains `softschema:generated` markers (see the guide’s “Keep
-Schema Tables In Sync With Generated Sections” playbook), run the re-renderer in
+Schema Tables in Sync with Generated Sections” playbook), run the re-renderer in
 `--check` mode so CI fails when the committed section lags behind the schema:
 
 ```bash
@@ -108,7 +106,7 @@ uv run softschema generate examples/movie_page/README.md --check
 
 Fix on drift: re-run without `--check` and commit the regenerated section.
 
-### Artifact validation
+### Artifact Validation
 
 Run `softschema validate` against every artifact under version control whose contract is
 fully defined:
@@ -154,7 +152,7 @@ jobs:
             --schema examples/movie_page/movie-page.schema.yaml
 ```
 
-### Pre-commit hook
+### Pre-Commit Hook
 
 For local runs before push, a `pre-commit` config that calls the same drift check:
 

{softschema-0.2.0 → softschema-0.2.2}/docs/e2e-testing.runbook.md

@@ -38,7 +38,7 @@ The automated half of the story runs on every push and PR
 | Python-vs-TypeScript byte parity | `cross-impl` job |
 | Tag ↔ `package.json` version match | `publish.yml` guard |
 
-**Not** covered by CI — the reason this runbook exists:
+**Not** covered by CI—the reason this runbook exists:
 
 - Installing the built wheel and npm tarball into clean environments and running them
   (entry points, bin shebang, bundled docs/skill resources).
@@ -86,7 +86,7 @@ This phase proves the **packaged artifacts** from a real install with no repo on
 the console entry points resolve, the bin shebang runs under plain Node, and the bundled
 docs/skill resources load from inside the installed package.
 
-### Python wheel in a fresh venv
+### Python Wheel in a Fresh Venv
 
 ```bash
 uv build
@@ -103,10 +103,10 @@ venv/bin/softschema validate spirited-away.md   # exit 0, structural ok, zero fl
 cd - && rm -rf "$tmp"
 ```
 
-### npm tarball under plain Node
+### npm Tarball under Plain Node
 
-`npm pack` runs `prepublishOnly` (build + publint), so the tarball is freshly rebuilt
-from source — the same artifact `npm publish` would upload.
+`npm pack` runs `prepublishOnly` (build and publint), so the tarball is freshly rebuilt
+from source—the same artifact `npm publish` would upload.
 Run it under `node` (>= 22.12), the runtime npm users get, not under bun:
 
 ```bash
@@ -153,7 +153,7 @@ diff movie-page.schema.yaml ts-schema.yaml    # byte-identical
 One trap to know about: the artifact names its own schema
 (`schema: movie-page.schema.yaml`), so the schema **must** be saved under that exact
 filename next to the artifact.
-Redirecting it anywhere else makes `validate` fail with `schema_missing` — correct
+Redirecting it anywhere else makes `validate` fail with `schema_missing`—correct
 resolution behavior, broken quickstart.
 If the README quickstart ever changes, re-verify the new text the same way before
 merging it.
@@ -177,21 +177,39 @@ present on disk.
 
 The tagging and release mechanics live in [publishing.md](publishing.md); this phase is
 what to run **after** `publish.yml` reports success for both registries.
-A just-published version sits inside the 14-day supply-chain cool-off, so pin the
-version and override the cutoff for the Python side:
+
+A just-published version sits inside the 14-day supply-chain cool-off, so the Python
+smoke test must override the cutoff.
+Three details make the difference between a real check and a false “no version” failure:
+
+- **Override the cutoff to *now*, not midnight.** `--exclude-newer-package` excludes
+  releases newer than the given instant.
+  A date-only value (`$(date +%F)`) is midnight UTC, which is *before* a version
+  published later the same day—so it excludes the very release you are verifying.
+  Use a full timestamp at the current moment (`$(date -u +%Y-%m-%dT%H:%M:%SZ)`); “now”
+  is always after the publish.
+- **Run from outside the repo.** From the project tree, uv reads its `[tool.uv]`
+  settings and applies the project’s own cool-off; a neutral directory (`cd /tmp`)
+  avoids that.
+- **`--refresh`** bypasses uv’s cached package index, which may not yet list a release
+  published seconds ago.
 
 ```bash
-uvx --exclude-newer-package "softschema=$(date +%F)" softschema@X.Y.Z --help
-npx softschema@X.Y.Z --help
+cd /tmp
+ts="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+uvx --refresh --exclude-newer-package "softschema=$ts" softschema@X.Y.Z --version
+npx -y softschema@X.Y.Z --version
 ```
 
 Then run the quickstart literally against the published artifacts:
 
 ```bash
 cd "$(mktemp -d)"
-uvx --exclude-newer-package "softschema=$(date +%F)" softschema@X.Y.Z docs example-artifact > spirited-away.md
-uvx --exclude-newer-package "softschema=$(date +%F)" softschema@X.Y.Z docs example-schema   > movie-page.schema.yaml
-uvx --exclude-newer-package "softschema=$(date +%F)" softschema@X.Y.Z validate spirited-away.md
+ts="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+uvx() { command uvx --refresh --exclude-newer-package "softschema=$ts" "$@"; }
+uvx softschema@X.Y.Z docs example-artifact > spirited-away.md
+uvx softschema@X.Y.Z docs example-schema   > movie-page.schema.yaml
+uvx softschema@X.Y.Z validate spirited-away.md
 ```
 
 Once the release ages past the cool-off, the unpinned `@latest` forms in the README

{softschema-0.2.0 → softschema-0.2.2}/docs/installation.md

@@ -9,11 +9,11 @@ Pick the runtime you already have; both validate against the same canonical sche
 |  | Pin as a dependency | Zero-install (`uvx` / `npx`) |
 | --- | --- | --- |
 | **For** | Projects, CI gates, library use | One-off checks, agent bootstrap |
-| **Reproducible** | Yes — the version is locked in `uv.lock` / `package-lock.json` | Only if you pin the runner (`uvx softschema@0.2.0`) |
-| **Fast / offline** | Yes — the binary is already on disk | Cold-start fetch; needs the network |
-| **Library import** | Yes — the only way | No |
+| **Reproducible** | Yes—the version is locked in `uv.lock` / `package-lock.json` | Only if you pin the runner (`uvx softschema@0.2.2`) |
+| **Fast / offline** | Yes—the binary is already on disk | Cold-start fetch; needs the network |
+| **Library import** | Yes—the only way | No |
 
-The rule of thumb: **if softschema runs more than once, or in CI, or you import it — pin
+The rule of thumb: **if softschema runs more than once, or in CI, or you import it—pin
 it as a dependency.
 For a quick one-off or an agent bootstrapping with nothing installed,
 use a zero-install runner**, pinned where the result must be repeatable.
@@ -23,14 +23,14 @@ use a zero-install runner**, pinned where the result must be repeatable.
 Python (a dev dependency, or a persistent user tool):
 
 ```bash
-uv add --dev softschema==0.2.0      # project dev dependency; run via `uv run softschema`
+uv add --dev softschema==0.2.2      # project dev dependency; run via `uv run softschema`
 uv tool install softschema          # persistent CLI on your PATH
 ```
 
 Node (>= 22.12):
 
 ```bash
-npm install -D softschema@0.2.0     # or: pnpm add -D / bun add -d
+npm install -D softschema@0.2.2     # or: pnpm add -D / bun add -d
 npx softschema --help               # resolves the local pinned copy
 ```
 
@@ -41,7 +41,7 @@ uvx softschema@latest --help        # Python implementation, ephemeral
 npx softschema@latest --help        # Node implementation, ephemeral
 ```
 
-Use `uvx softschema@0.2.0` / `npx -y softschema@0.2.0` when a repeated ad-hoc run must
+Use `uvx softschema@0.2.2` / `npx -y softschema@0.2.2` when a repeated ad-hoc run must
 resolve the same version every time.
 
 ## Quick Start for Agents
@@ -79,7 +79,7 @@ A gate such as npm’s `--before` / `NPM_CONFIG_BEFORE`, pnpm’s `minimumReleas
 uv’s `--exclude-newer` resolves `@latest` to the newest release old enough to pass, so
 you get the freshest vetted version without pinning.
 A just-published version installs only once it ages past the cutoff.
-Consumer projects should still pin their own dependency — a project’s reproducibility is
+Consumer projects should still pin their own dependency—a project’s reproducibility is
 the project’s responsibility, not the publisher’s cool-off.
 See [supply-chain-hardening](https://github.com/jlevy/supply-chain-hardening) for the
 rationale.

{softschema-0.2.0 → softschema-0.2.2}/docs/publishing.md

@@ -102,16 +102,25 @@ For each release of version `X.Y.Z`:
    git push origin vX.Y.Z
    ```
 
+   If the environment blocks pushing tags over git (some hosted or proxied checkouts
+   allow branch pushes but reject tag refs with a `403`), skip the `git push` and let
+   the next step create the tag: passing `--target` with the merge-commit SHA to
+   `gh release create` creates the tag at that commit as part of publishing the release.
+
 6. **Create the GitHub release** (this triggers the publish workflow, which publishes to
    both PyPI and npm over OIDC in one run):
 
    ```bash
-   gh release create vX.Y.Z --title "softschema X.Y.Z" --notes "..."
+   gh release create vX.Y.Z --title "softschema X.Y.Z" --notes-file notes.md
+   # when the tag was not pushed in step 5, create it here at the merge commit:
+   gh release create vX.Y.Z --target MERGE_SHA --title "softschema X.Y.Z" --notes-file notes.md
    ```
 
-   Write the notes from the release’s behavior/breaking changes (see prior releases for
-   the shape: a one-line summary, then “Behavior changes”, “Fixes and hardening”, and
-   “Testing and release safety” sections).
+   Write the notes from the release’s behavior and breaking changes (see prior releases
+   for the shape: a one-line summary, then sections for breaking changes, new features,
+   fixes and hardening, and testing and release safety).
+   Use a notes file for multi-section notes; the inline `--notes` flag is fine only for
+   a one-liner.
 
 7. **Watch the workflow** until both `Publish to PyPI` and `Publish to npm` report
    success:
@@ -124,14 +133,20 @@ For each release of version `X.Y.Z`:
    artifacts (end-to-end runbook Phase 5):
 
    ```bash
-   uvx --exclude-newer-package "softschema=$(date +%F)" softschema@X.Y.Z --help
-   npx softschema@X.Y.Z --help
+   cd /tmp                                   # outside the repo: do not inherit its [tool.uv] cool-off
+   ts="$(date -u +%Y-%m-%dT%H:%M:%SZ)"       # cutoff = now, so a same-day publish is included
+   uvx --refresh --exclude-newer-package "softschema=$ts" softschema@X.Y.Z --version
+   npx -y softschema@X.Y.Z --version
    ```
 
-   (The `--exclude-newer-package` override is needed because the publish workflow sets
-   `UV_EXCLUDE_NEWER` to a 14-day cool-off cutoff for supply-chain hygiene.
-   Anyone consuming the freshly published version with that policy sees the same
-   friction for ~14 days; this is intentional.)
+   The `--exclude-newer-package` override is needed because a freshly published version
+   sits inside the 14-day supply-chain cool-off; anyone consuming it under that policy
+   sees the same friction for ~14 days, which is intentional.
+   Three details matter for the smoke test: use a full timestamp at the current moment
+   (a date-only `$(date +%F)` is midnight UTC and excludes a version published later the
+   same day), run from outside the repo so uv does not apply the project’s own cool-off,
+   and pass `--refresh` so uv does not serve a cached index that predates the publish
+   (see runbook Phase 5).
 
 <!-- This document follows common-doc-guidelines.md.
 See github.com/jlevy/practical-prose and review guidelines before editing.

{softschema-0.2.0 → softschema-0.2.2}/docs/softschema-guide.md

@@ -50,7 +50,7 @@ against a named contract.
 The practice is language neutral; another project could implement it with any of JSON
 Schema, database records, or hand-written validators.
 
-## When To Use It
+## When to Use It
 
 Reach for softschema when all three of these hold:
 
@@ -178,7 +178,7 @@ Picking a version:
 - Additive, optional fields usually don’t need a version bump.
 - Keep versions short (`v1`, `v2`, `1.0`).
 
-## Playbook: Adopt softschema For An Existing Markdown Artifact
+## Playbook: Adopt softschema for an Existing Markdown Artifact
 
 Start with one document type, not a whole repository:
 
@@ -234,7 +234,7 @@ The body stays unchanged.
 A consumer that aggregates incidents now reads `incident.affected_service` from YAML
 instead of trying to grep the body.
 
-## Playbook: Choose Which Values Belong In YAML
+## Playbook: Choose Which Values Belong in YAML
 
 The hardest call in adoption is “what goes in YAML, what stays prose?”
 Use the promotion path step by step:
@@ -270,7 +270,7 @@ file. The contract ID stays; only the shell changes.
 A field is ready to promote when: a consumer extracts it, the value type is stable, and
 emitting it consistently is easier than parsing it from prose.
 
-## Playbook: Inline Frontmatter Vs Companion Data
+## Playbook: Inline Frontmatter vs. Companion Data
 
 The rule of thumb is **inline-small, companion-large**:
 
@@ -397,7 +397,7 @@ The `result` object reports `structural` (JSON Schema) and `semantic` (Pydantic)
 separately, so callers can distinguish “shape was wrong” from “cross-field invariant
 failed” without parsing error strings.
 
-## Playbook: Annotate Fields With SoftField
+## Playbook: Annotate Fields with SoftField
 
 `SoftField` is an optional wrapper over Pydantic’s `Field` that records per-field
 authoring metadata (`group`, `owner`, `tier`, `instruction`, `examples`, `aliases`,
@@ -435,7 +435,7 @@ controlled-vocabulary case.
 The recognized keys and the full call shape are documented in
 [Python Package Design](softschema-python-design.md).
 
-## Playbook: Keep Schema Tables In Sync With Generated Sections
+## Playbook: Keep Schema Tables in Sync with Generated Sections
 
 When a controlled vocabulary or field list appears in two places (a schema and a runbook
 table), it will drift.
@@ -478,7 +478,7 @@ A worked example lives in
 [examples/movie_page/README.md](../examples/movie_page/README.md); the “Schema Enums”
 section is regenerated from the movie schema.
 
-## Playbook: Validate In CI
+## Playbook: Validate in CI
 
 Pin softschema as a dev dependency so CI uses a known version:
 
@@ -521,7 +521,7 @@ Two checks belong in CI:
 For a full GitHub Actions snippet and a `pre-commit` hook example, see the “Continuous
 integration” section of [docs/development.md](development.md).
 
-## Playbook: Migrate An Existing Artifact
+## Playbook: Migrate an Existing Artifact
 
 Take an artifact that doesn’t fit the canonical shape and bring it in line.
 
@@ -631,7 +631,7 @@ The consumer reads YAML now.
 For each migration, set `status: soft` or `permissive` initially.
 Tighten only after existing instances validate cleanly.
 
-## Playbook: Use softschema With Agents
+## Playbook: Use softschema with Agents
 
 softschema is built for documents that humans and coding agents both write.
 A few patterns help agents do the right thing:
@@ -686,7 +686,7 @@ A few patterns help agents do the right thing:
 - **Promoting prose that no consumer reads.** Leave background, analysis, and caveats as
   prose. Promote a value only when a code path, QA check, or aggregation reads it.
 
-## Relationship To The Packages
+## Relationship to the Packages
 
 Two interchangeable packages implement the language-neutral pattern at exact behavioral
 parity, Python/Pydantic and TypeScript/Zod.
@@ -759,8 +759,7 @@ For Python-specific module layout, public API decisions, and dependency boundary
 - [Movie Page Example](../examples/movie_page/README.md): the complete public example
   backing the snippets above.
 - [Installation](installation.md), [Development](development.md), and
-  [Publishing](https://github.com/jlevy/softschema/blob/main/docs/publishing.md):
-  workflow docs.
+  [Publishing](publishing.md): workflow docs.
 
 <!-- This document follows common-doc-guidelines.md.
 See github.com/jlevy/practical-prose and review guidelines before editing.

{softschema-0.2.0 → softschema-0.2.2}/docs/softschema-python-design.md

@@ -48,8 +48,7 @@ It should orient a new visitor, show the main example, and point to the guide an
 rather than repeating their content.
 
 Template workflow docs keep template names: [development.md](development.md),
-[installation.md](installation.md), and
-[publishing.md](https://github.com/jlevy/softschema/blob/main/docs/publishing.md).
+[installation.md](installation.md), and [publishing.md](publishing.md).
 Package design details live in this document unless they grow large enough to justify a
 separate reference.
 
@@ -183,7 +182,7 @@ A relative `schema_path` is resolved against only the document directory and the
 working directory, so resolution is predictable and never binds to an unrelated compiled
 schema in a parent directory.
 
-### Engine-neutral structural errors
+### Engine-Neutral Structural Errors
 
 Structural validation runs through `jsonschema`, but the error records it returns are
 synthesized by softschema, not passed through from the library.
@@ -204,7 +203,7 @@ to stderr; the package version comes from `importlib.metadata` via
 `softschema-py` (the latter pairs with a future `softschema-ts` for the shared golden
 corpus).
 
-### Skill resource and mirrors
+### Skill Resource and Mirrors
 
 `skills/softschema/SKILL.md` is the source skill.
 `softschema skill --install` writes full generated copies to
@@ -242,7 +241,7 @@ if any(w.code.startswith("document-") for w in result.warnings):
 A regression test (`tests/test_warning_codes.py`) holds the table to the enum: any new
 emitted code that isn’t a `WarningCode` member fails CI.
 
-### Structural error kinds
+### Structural Error Kinds
 
 `StructuralResult.errors[*].kind` uses a separate `snake_case` namespace because errors
 are blocking, not advisory.

{softschema-0.2.0 → softschema-0.2.2}/docs/softschema-spec.md

@@ -41,7 +41,7 @@ These terms are used throughout; each is defined here before it appears in a rul
 | **metadata block** | The `softschema:` mapping in the frontmatter (or at the document root for pure YAML). It holds softschema’s own keys, not payload data. |
 | **payload** | The structured values a consumer reads, validated against a contract. |
 | **envelope** | The single top-level key whose value is the payload; the **envelope key** is its name (for example `movie:`). |
-| **contract** | The named payload contract — *what* the payload is. |
+| **contract** | The named payload contract—*what* the payload is. |
 | **contract ID** | The string that names the contract (for example `example.movies:MoviePage/v1`). |
 | **model** | A Pydantic class or Zod schema: a language-specific *source* for a contract. |
 | **compiled schema** | The JSON Schema (written as YAML or JSON) that a model compiles to; the language-neutral form of the contract. |
@@ -212,7 +212,7 @@ An implementation must:
 
 For example, the movie artifact above carries both `title:` and `movie:`. With two
 non-`softschema` keys, inference does not apply, so the artifact declares
-`envelope: movie` in its metadata block — `title:` stays an uninterpreted host key, and
+`envelope: movie` in its metadata block—`title:` stays an uninterpreted host key, and
 the artifact validates with no flags.
 A caller can still override with `--envelope` on a given run.
 
@@ -242,7 +242,7 @@ product-tag `namespace`, and short versions (`v1`, `1.0`). Examples:
 - `com.acme.docs:IncidentReview/1.0`
 
 A contract ID may correspond to a Pydantic class, a Zod export, a precompiled JSON
-Schema, a database record, or a hand-authored validator — all equally valid.
+Schema, a database record, or a hand-authored validator—all equally valid.
 It is not required to be an import path or a class name.
 
 ## Status Values
@@ -282,7 +282,7 @@ Markdown body prose and tables are reader-facing and never authoritative.
 
 A compiled schema is a generated validation contract, usually JSON Schema written as
 YAML. It is the language-neutral form of a contract: a Pydantic class or Zod schema
-compiles to it (provably identically — the conformance machinery guarantees an equal
+compiles to it (provably identically—the conformance machinery guarantees an equal
 `schema_sha256`), and any language can validate against it.
 
 An artifact may bind to its compiled schema with the optional `softschema.schema` key.
@@ -292,7 +292,7 @@ The compiled schema a validator uses is resolved in this precedence (highest fir
    library call.
 2. A host registry binding (a registered contract’s schema path; library path only).
 3. The `softschema.schema` document metadata.
-4. None — a metadata-only check (contract/status/envelope rules, no schema).
+4. None—a metadata-only check (contract/status/envelope rules, no schema).
 
 Host-controlled configuration outranks document metadata on purpose: a document must not
 silently redirect a host’s validation to a schema the host did not choose.
@@ -302,8 +302,8 @@ none, which is what lets a self-describing artifact validate with no flags.
 Resolution of a `softschema.schema` value is, by convention, relative to the document
 that carries it; this spec requires only that the value be a non-empty string and leaves
 the exact resolution to the host, because file layout is situational.
-(The reference CLIs accept only relative values in metadata — an absolute path must use
-`--schema` — resolve them from the document’s directory, and reject a path whose
+(The reference CLIs accept only relative values in metadata—an absolute path must use
+`--schema`—resolve them from the document’s directory, and reject a path whose
 normalized result escapes both the document directory and the working directory.)
 
 A compiled schema is not a per-document companion data file.
@@ -335,6 +335,18 @@ A validator must reject:
 - undeclared payload fields rejected by the `enforced` strictness rule (see Status
   Values)
 
+Validation output is deterministic across conforming implementations: structural error
+records share an engine-neutral shape and message wording, and numbers — in an error
+record’s `value`/`validator_value`, in a synthesized message, and in an echoed payload —
+render in a canonical form, where a whole-valued number carries no trailing fraction
+(`2`, not `2.0`).
+Output is byte-identical for every number an implementation can represent exactly:
+integers and whole-valued numbers within the IEEE-754 safe-integer range (`abs < 2^53`),
+and ordinary floats.
+A whole-valued magnitude at or beyond 2^53 is out of scope, because an arbitrary-precision
+integer runtime and a double-only runtime cannot always render it identically; validated
+payloads should avoid such literals.
+
 ## Generated Sections
 
 A conforming implementation may regenerate Markdown sections from a compiled schema
@@ -366,8 +378,8 @@ Recognized attributes:
 file path. This is a 0.2.0 change; a marker that still uses `contract="...path..."` is
 rejected with a message pointing at the rename.)
 
-The output is normative — equal inputs produce byte-equal output, and an implementation
-is checked against this spec, not the other way around:
+The output is normative—equal inputs produce byte-equal output, and an implementation is
+checked against this spec, not the other way around:
 
 - **`enum_table`**: a GFM table with header row `| Field | Allowed values |`; one row
   per string-enum property of the schema, in the schema’s property order; the field name
@@ -377,7 +389,7 @@ is checked against this spec, not the other way around:
   branch is rendered); any other enum shape is skipped.
   With no enum-valued properties the single row is `| _(no enum fields)_ | _(none)_ |`.
 - **`field_list`**: one bullet per top-level property, in schema order:
-  `- `name` (type, required): description` — the JSON type label, `required` or
+  `- `name` (type, required): description`—the JSON type label, `required` or
   `optional`, then `: description` only when the property has one.
   Nested properties are not listed (they appear through their parent’s type).
   With no properties the single bullet is `- _(no fields)_`.