softschema 0.2.1__tar.gz → 0.3.0__tar.gz

{softschema-0.2.1 → softschema-0.3.0}/AGENTS.md

@@ -11,9 +11,9 @@ Start here:
 
 softschema ships two interchangeable implementations with the same CLI and library
 surface: Python/Pydantic (`softschema`, `softschema-py`) and TypeScript/Zod
-(`softschema`, `softschema-ts`). They are held to exact behavioral parity: same flags,
-same canonical compiled JSON Schema, same validation results, so authoring an artifact
-is identical regardless of which you run.
+(`softschema`, `softschema-ts`). They share commands, exit classes, structured result
+meaning, and canonical compiled JSON Schema, so authoring an artifact is identical
+regardless of which you run.
 
 For implementer reference (only when changing a package itself):
 
@@ -63,12 +63,12 @@ Documentation rules:
 - Include the standard documentation footer in repo docs.
   Do not add it to authored softschema example artifacts.
 
-<!-- BEGIN TBD INTEGRATION format=f04 surface=agents-md -->
+<!-- BEGIN TBD INTEGRATION format=f06 surface=agents-md -->
 ## tbd
 
 This repository uses **tbd** for git-native issue tracking (beads), spec-driven
 planning, and on-demand engineering guidelines.
-As the agent, you operate tbd on the user’s behalf — translate their requests into tbd
+As the agent, you operate tbd on the user’s behalf: translate their requests into tbd
 actions rather than telling them to run commands.
 
 - Run `tbd prime` to load current project state and the full tbd workflow.

{softschema-0.2.1 → softschema-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: softschema
-Version: 0.2.1
+Version: 0.3.0
 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
@@ -43,17 +43,17 @@ uvx softschema@latest docs example-schema > movie-page.schema.yaml
 uvx softschema@latest validate spirited-away.md
 ```
 
-(Or `npx softschema@latest ...` for the Node implementation; the two are
+(Or `npx -y softschema@latest ...` for the Node implementation; the two are
 interchangeable.)
 
 To set up softschema in a repository with an agent, tell the agent:
 
 > Run `uvx softschema@latest --help` (for the Python implementation) or
-> `npx softschema@latest --help` (for the Node implementation) and follow the
+> `npx -y softschema@latest --help` (for the Node implementation) and follow the
 > instructions to set up softschema for this repo as a skill.
 
-The help output points the agent to `skill --install`, which writes discoverable
-`SKILL.md` mirrors for Codex, Claude Code, Gemini CLI, and other coding agents.
+The help output points the agent to the explicit install command, which writes the
+portable Agent Skills location and the Claude Code discovery mirror.
 
 ## What Are Soft Schemas?
 
@@ -228,25 +228,27 @@ via `--schema` executes nothing and is the safe path for untrusted input.
 
 Two supported ways to consume softschema; pick by use:
 
-- **Pin it as a dependency** for projects, CI gates, and library use (reproducible,
-  fast, offline, and the only way to `import` it):
+- **Install it as a dependency** for projects, CI gates, and library use (reproducible
+  through the project lockfile, fast, offline, and the only way to `import` it):
 
   ```bash
-  uv add --dev softschema==0.2.1        # Python
-  npm install -D softschema@0.2.1       # Node (or: bun add -d)
+  uv add --dev softschema               # Python
+  npm install -D softschema@latest      # Node (or: bun add -d)
   ```
 
 - **Zero-install** for one-off checks and agent bootstrap:
 
   ```bash
   uvx softschema@latest --help
-  npx softschema@latest --help
+  npx -y softschema@latest --help
   ```
 
-The rule of thumb: if softschema runs more than once, or in CI, or you import it—pin it.
+The rule of thumb: if softschema runs more than once, or in CI, or you import it—install
+it in the project and commit the lockfile.
 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.
+runner.
+See [Installation](docs/installation.md) for details and the project supply-chain
+policy.
 
 ## Use as a Library
 
@@ -279,8 +281,9 @@ See the [softschema Guide](docs/softschema-guide.md) for the full playbooks.
 ## Use as an Agent Skill
 
 Both packages ship the same [`SKILL.md`](https://agentskills.io) following the open
-Agent Skills standard discovered by Claude Code, Codex, Gemini CLI, Cursor, Copilot, and
-~20 other coding agents.
+Agent Skills standard.
+The portable mirror works with agents that discover `.agents`; the optional Claude
+mirror supports Claude Code’s discovery path.
 Pointing an agent at the CLI is enough to bootstrap its understanding of the soft-schema
 approach: the `--help` epilog routes it to `skill --install`, a brief, and the bundled
 docs.
@@ -288,23 +291,23 @@ docs.
 ```bash
 # Python:
 uvx softschema@latest --help            # entry point with skill setup pointers
-uvx softschema@latest skill --install   # install repo-local skill mirrors
+uvx softschema@latest skill --install --scope project --agent portable --agent claude
 uvx softschema@latest skill --brief     # compact operating brief
 uvx softschema@latest docs guide        # full mental model and adoption path
 
 # TypeScript (same commands, same bundled docs/skill):
-npx softschema@latest --help
-npx softschema@latest skill --install
-npx softschema@latest skill --brief
-npx softschema@latest docs guide
+npx -y softschema@latest --help
+npx -y softschema@latest skill --install --scope project --agent portable --agent claude
+npx -y softschema@latest skill --brief
+npx -y softschema@latest docs guide
 ```
 
 Self-install the skill into a project so any agent working in the repo finds it natively
 (either package writes the identical mirrors):
 
 ```bash
-uvx softschema@latest skill --install
-# or: npx softschema@latest skill --install
+uvx softschema@latest skill --install --scope project --agent portable --agent claude
+# or: npx -y softschema@latest skill --install --scope project --agent portable --agent claude
 # writes:
 #   .agents/skills/softschema/SKILL.md   (Codex, Gemini CLI, cross-agent installers)
 #   .claude/skills/softschema/SKILL.md   (Claude Code mirror)
@@ -323,12 +326,10 @@ library surface:
 - **TypeScript / Zod**: [`softschema`](docs/softschema-typescript-design.md) on npm (run
   as `softschema` or `softschema-ts`).
 
-The two are held to **exact behavioral parity**: equivalent CLI inputs, outputs, and
-flags; equivalent library APIs; the same canonical compiled JSON Schema
-(content-identical, with an equal `schema_sha256` fingerprint); and the same
-engine-neutral validation results.
-Every behavior change lands in a shared golden-test corpus first, then in both packages,
-and CI fails if their outputs or compiled schemas drift.
+The two share the same commands, exit classes, structured result meaning, canonical
+compiled JSON Schema, and `schema_sha256` fingerprint.
+Human-readable presentation and model-native errors may differ where the runtime does;
+shared vectors and broad CLI journeys keep the portable contract aligned.
 They release together under the same version number on PyPI and npm.
 
 ## Further Reading

{softschema-0.2.1 → softschema-0.3.0}/README.md

@@ -15,17 +15,17 @@ uvx softschema@latest docs example-schema > movie-page.schema.yaml
 uvx softschema@latest validate spirited-away.md
 ```
 
-(Or `npx softschema@latest ...` for the Node implementation; the two are
+(Or `npx -y softschema@latest ...` for the Node implementation; the two are
 interchangeable.)
 
 To set up softschema in a repository with an agent, tell the agent:
 
 > Run `uvx softschema@latest --help` (for the Python implementation) or
-> `npx softschema@latest --help` (for the Node implementation) and follow the
+> `npx -y softschema@latest --help` (for the Node implementation) and follow the
 > instructions to set up softschema for this repo as a skill.
 
-The help output points the agent to `skill --install`, which writes discoverable
-`SKILL.md` mirrors for Codex, Claude Code, Gemini CLI, and other coding agents.
+The help output points the agent to the explicit install command, which writes the
+portable Agent Skills location and the Claude Code discovery mirror.
 
 ## What Are Soft Schemas?
 
@@ -200,25 +200,27 @@ via `--schema` executes nothing and is the safe path for untrusted input.
 
 Two supported ways to consume softschema; pick by use:
 
-- **Pin it as a dependency** for projects, CI gates, and library use (reproducible,
-  fast, offline, and the only way to `import` it):
+- **Install it as a dependency** for projects, CI gates, and library use (reproducible
+  through the project lockfile, fast, offline, and the only way to `import` it):
 
   ```bash
-  uv add --dev softschema==0.2.1        # Python
-  npm install -D softschema@0.2.1       # Node (or: bun add -d)
+  uv add --dev softschema               # Python
+  npm install -D softschema@latest      # Node (or: bun add -d)
   ```
 
 - **Zero-install** for one-off checks and agent bootstrap:
 
   ```bash
   uvx softschema@latest --help
-  npx softschema@latest --help
+  npx -y softschema@latest --help
   ```
 
-The rule of thumb: if softschema runs more than once, or in CI, or you import it—pin it.
+The rule of thumb: if softschema runs more than once, or in CI, or you import it—install
+it in the project and commit the lockfile.
 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.
+runner.
+See [Installation](docs/installation.md) for details and the project supply-chain
+policy.
 
 ## Use as a Library
 
@@ -251,8 +253,9 @@ See the [softschema Guide](docs/softschema-guide.md) for the full playbooks.
 ## Use as an Agent Skill
 
 Both packages ship the same [`SKILL.md`](https://agentskills.io) following the open
-Agent Skills standard discovered by Claude Code, Codex, Gemini CLI, Cursor, Copilot, and
-~20 other coding agents.
+Agent Skills standard.
+The portable mirror works with agents that discover `.agents`; the optional Claude
+mirror supports Claude Code’s discovery path.
 Pointing an agent at the CLI is enough to bootstrap its understanding of the soft-schema
 approach: the `--help` epilog routes it to `skill --install`, a brief, and the bundled
 docs.
@@ -260,23 +263,23 @@ docs.
 ```bash
 # Python:
 uvx softschema@latest --help            # entry point with skill setup pointers
-uvx softschema@latest skill --install   # install repo-local skill mirrors
+uvx softschema@latest skill --install --scope project --agent portable --agent claude
 uvx softschema@latest skill --brief     # compact operating brief
 uvx softschema@latest docs guide        # full mental model and adoption path
 
 # TypeScript (same commands, same bundled docs/skill):
-npx softschema@latest --help
-npx softschema@latest skill --install
-npx softschema@latest skill --brief
-npx softschema@latest docs guide
+npx -y softschema@latest --help
+npx -y softschema@latest skill --install --scope project --agent portable --agent claude
+npx -y softschema@latest skill --brief
+npx -y softschema@latest docs guide
 ```
 
 Self-install the skill into a project so any agent working in the repo finds it natively
 (either package writes the identical mirrors):
 
 ```bash
-uvx softschema@latest skill --install
-# or: npx softschema@latest skill --install
+uvx softschema@latest skill --install --scope project --agent portable --agent claude
+# or: npx -y softschema@latest skill --install --scope project --agent portable --agent claude
 # writes:
 #   .agents/skills/softschema/SKILL.md   (Codex, Gemini CLI, cross-agent installers)
 #   .claude/skills/softschema/SKILL.md   (Claude Code mirror)
@@ -295,12 +298,10 @@ library surface:
 - **TypeScript / Zod**: [`softschema`](docs/softschema-typescript-design.md) on npm (run
   as `softschema` or `softschema-ts`).
 
-The two are held to **exact behavioral parity**: equivalent CLI inputs, outputs, and
-flags; equivalent library APIs; the same canonical compiled JSON Schema
-(content-identical, with an equal `schema_sha256` fingerprint); and the same
-engine-neutral validation results.
-Every behavior change lands in a shared golden-test corpus first, then in both packages,
-and CI fails if their outputs or compiled schemas drift.
+The two share the same commands, exit classes, structured result meaning, canonical
+compiled JSON Schema, and `schema_sha256` fingerprint.
+Human-readable presentation and model-native errors may differ where the runtime does;
+shared vectors and broad CLI journeys keep the portable contract aligned.
 They release together under the same version number on PyPI and npm.
 
 ## Further Reading

{softschema-0.2.1 → softschema-0.3.0}/docs/development.md

@@ -174,16 +174,17 @@ your repository.
 ## Keeping Python and TypeScript in Parity
 
 softschema ships two implementations, Python/Pydantic (`softschema`) and TypeScript/Zod
-(`softschema`, `softschema-ts`), held to **exact behavioral parity**: equivalent CLI
-inputs/outputs/flags and library APIs, the same canonical compiled JSON Schema
-(content-identical, equal `schema_sha256`), and the same engine-neutral validation
-results. Only idiomatic surface differs (snake_case ↔ camelCase, Pydantic ↔ Zod).
+(`softschema`, `softschema-ts`), with the same commands, exit classes, structured result
+meaning, canonical compiled JSON Schema, and `schema_sha256`. Only idiomatic surface
+details differ (snake_case ↔ camelCase, Pydantic ↔ Zod), and cross-runtime JSON output
+is compared structurally rather than as presentation bytes.
 
 When you change any behavior, follow this loop so the two never drift:
 
-1. **Golden first.** Write or update the shared scenario in `tests/golden/scenarios/`
-   (neutral, runs on both) or `tests/golden/scenarios-{py,ts}/` (per-language
-   invocation, identical output) **before** touching code.
+1. **Choose one primary owner first.** Use a shared YAML vector for a portable library
+   rule, an adapter unit test for runtime-specific integration, or a golden journey for
+   public CLI output and exit behavior.
+   Do not add the same case at every layer.
 2. **Implement in Python**, then `uv run pytest` and
    `SOFTSCHEMA_IMPL=py bash tests/golden/run.sh`.
 3. **Port to TypeScript**, then `bun test` (in `packages/typescript`) and
@@ -198,7 +199,7 @@ The parity invariants, and where each is enforced:
 | --- | --- |
 | Canonical schema (equal `schema_sha256`) | `compile` and the KitchenSink conformance test (`packages/typescript/test/conformance.test.ts`) and `examples/parity/` |
 | Engine-neutral structural errors | shared message templates (`errors`), the golden corpus |
-| Byte-identical neutral CLI output | the shared golden corpus (run twice via `SOFTSCHEMA_IMPL`) |
+| Structurally equal JSON and exact stable human output | the shared golden corpus (run twice via `SOFTSCHEMA_IMPL`) |
 | Equal flag/command surface | per-impl and neutral golden scenarios |
 | Bundled docs/skill resolve from the package | the standalone test (`packages/typescript/test/standalone.test.ts`) |
 | Skill mirrors never go stale | the mirror drift test (`tests/test_skill_mirror_drift.py`) |

{softschema-0.2.1 → softschema-0.3.0}/docs/e2e-testing.runbook.md

@@ -35,7 +35,7 @@ The automated half of the story runs on every push and PR
 | TS typecheck, biome, unit tests + coverage gate | `typescript` job |
 | TS build + publint (publishable layout) | `typescript` job |
 | Golden corpus on py, ts (Node), ts-bun | `golden` + `typescript` jobs |
-| Python-vs-TypeScript byte parity | `cross-impl` job |
+| Python-vs-TypeScript semantic parity | `cross-impl` job |
 | Tag ↔ `package.json` version match | `publish.yml` guard |
 
 **Not** covered by CI—the reason this runbook exists:
@@ -55,16 +55,16 @@ Mirror CI from the repo root, in this order (later phases depend on the builds):
 ```bash
 make install        # uv sync + npm install (lefthook) + bun install
 make lint-check     # codespell, ruff, basedpyright, doc footers
-uv run pytest       # Python unit tests (142 as of 0.2.0)
+uv run pytest       # Python unit tests
 uv build            # wheel + sdist into dist/ (used by Phase 2)
 
 cd packages/typescript
-bun run check       # biome + tsc + bun test with coverage gate (160 tests as of 0.2.0)
+bun run check       # biome + tsc + bun test with coverage gate
 bun run build       # copy-resources + bunup → dist/ (required by the ts golden runs)
 bun run publint
 cd ../..
 
-SOFTSCHEMA_IMPL=py     bash tests/golden/run.sh   # 46 scenarios as of 0.2.0
+SOFTSCHEMA_IMPL=py     bash tests/golden/run.sh
 SOFTSCHEMA_IMPL=ts     bash tests/golden/run.sh   # 44
 SOFTSCHEMA_IMPL=ts-bun bash tests/golden/run.sh   # 46
 bash tests/golden/cross-impl-diff.sh              # "cross-impl parity OK"
@@ -128,9 +128,9 @@ If a local supply-chain cool-off blocks the `npm install` of dependencies, add
 ## Phase 3: The Quickstart, As Written
 
 The README Quick Start is the contract with a first-time user; run it verbatim from an
-**empty directory**, on both implementations, and byte-compare.
-Before a release, substitute the local builds for `uvx softschema@latest` /
-`npx softschema@latest` (the published forms are verified in Phase 5):
+**empty directory** on both implementations.
+Before a release, substitute the local builds for the zero-install `@latest` commands
+shown in the README (the published forms are verified in Phase 5):
 
 ```bash
 repo=$(pwd)   # the softschema checkout
@@ -166,7 +166,7 @@ from Phase 2 or 3:
 
 ```bash
 cd "$(mktemp -d)" && git init -q .
-softschema skill --install
+softschema skill --install --scope project --agent portable --agent claude
 ls .agents/skills/softschema/SKILL.md .claude/skills/softschema/SKILL.md
 ```
 
@@ -212,8 +212,8 @@ 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
-resolve to it with no override.
+The README, bundled skill, CLI help, and installation guide use `@latest`, so published
+release verification requires no follow-up documentation pin change.
 
 ## Recording Results
 

{softschema-0.2.1 → softschema-0.3.0}/docs/installation.md

@@ -6,55 +6,61 @@ Pick the runtime you already have; both validate against the same canonical sche
 
 ## Two Ways to Consume It
 
-|  | Pin as a dependency | Zero-install (`uvx` / `npx`) |
+|  | Install 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.1`) |
+| **Reproducible** | Yes—the version is locked in `uv.lock` / `package-lock.json` | No—`@latest` resolves at invocation time |
 | **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
-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.
+The rule of thumb: **if softschema runs more than once, or in CI, or you import it—add
+it as a project dependency and commit the lockfile.
+For a quick one-off or an agent bootstrapping with nothing installed, use a zero-install
+runner**.
 
-## Pin as a Dependency
+## Install as a Dependency
 
 Python (a dev dependency, or a persistent user tool):
 
 ```bash
-uv add --dev softschema==0.2.1      # project dev dependency; run via `uv run softschema`
+uv add --dev softschema             # 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.1     # or: pnpm add -D / bun add -d
+npm install -D softschema@latest    # or: pnpm add -D / bun add -d
 npx softschema --help               # resolves the local pinned copy
 ```
 
 ## Zero-Install
 
 ```bash
-uvx softschema@latest --help        # Python implementation, ephemeral
-npx softschema@latest --help        # Node implementation, ephemeral
+uvx softschema@latest --help       # Python implementation, ephemeral
+npx -y softschema@latest --help    # Node implementation, ephemeral
 ```
 
-Use `uvx softschema@0.2.1` / `npx -y softschema@0.2.1` when a repeated ad-hoc run must
-resolve the same version every time.
+These commands resolve the latest published release.
+Use the project-dependency path above when a workflow must be repeatable.
 
 ## Quick Start for Agents
 
 To set up softschema in a repository with an agent, tell the agent:
 
 > Run `uvx softschema@latest --help` (for the Python implementation) or
-> `npx softschema@latest --help` (for the Node implementation) and follow the
+> `npx -y softschema@latest --help` (for the Node implementation) and follow the
 > instructions to set up softschema for this repo as a skill.
 
-The help output points the agent to `skill --install`, which writes
-`.agents/skills/softschema/SKILL.md` and `.claude/skills/softschema/SKILL.md` from the
-repository root.
+The help output points to the explicit project install:
+
+```bash
+softschema skill --install --scope project --agent portable --agent claude
+```
+
+This writes `.agents/skills/softschema/SKILL.md` and
+`.claude/skills/softschema/SKILL.md` from the repository root.
+Use one `--agent` when only one mirror is wanted; use `--dry-run` to preview.
 
 ## Installing uv
 
@@ -73,14 +79,10 @@ brew install uv
 
 ## Supply-chain Cool-off
 
-`@latest` is the recommended form for the agent-bootstrap path, including under a
-release-age cool-off.
-A gate such as npm’s `--before` / `NPM_CONFIG_BEFORE`, pnpm’s `minimumReleaseAge`, or
-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
-the project’s responsibility, not the publisher’s cool-off.
+Zero-install commands use `@latest` for low-friction one-off checks and agent bootstrap.
+They are intentionally not reproducible.
+Projects and CI should install softschema as a dependency, commit the normal lockfile,
+and apply a release-age cool-off when updating it.
 See [supply-chain-hardening](https://github.com/jlevy/supply-chain-hardening) for the
 rationale.
 

{softschema-0.2.1 → softschema-0.3.0}/docs/publishing.md

@@ -19,15 +19,12 @@ No API tokens are stored in the repo.
   to `X.Y.Z` in the same commit that prepares the release, so the npm version matches
   the Git tag the Python build derives.
   CI verifies this match before publishing and fails the release on a mismatch.
-- **Docs and the skill use `@latest`, not a pinned version.** README, the skill, and
-  other human- and agent-facing material invoke `uvx softschema@latest` /
-  `npx softschema@latest`, so there is no per-release pin to bump.
-  This is safe here because the repo’s supply-chain policy enforces a 14-day cool-off
-  (`UV_EXCLUDE_NEWER` / `--exclude-newer-package`; see
-  `tbd guidelines supply-chain-hardening`), so `@latest` resolves to the newest release
-  that has already cleared the cool-off window rather than a just-published one.
-- The committed skill mirrors under `.agents/` and `.claude/` are regenerated by
-  `softschema skill --install`; a drift test keeps them in sync with the source.
+- **Zero-install examples use `@latest`.** This keeps the README, installation guide,
+  shipped skill, and CLI help stable across releases.
+  Repeatable project and CI use belongs in a lockfile-backed dependency instead.
+- The committed skill mirrors under `.agents/` and `.claude/` are regenerated with the
+  explicit project-scope install command; a drift test keeps them in sync with the
+  source.
 - Patch bumps (`0.1.Z`) cover docs-only changes and small additive features.
   Reserve minor bumps (`0.Y.0`) for changes that meaningfully shift the API or spec.
 
@@ -79,8 +76,7 @@ For each release of version `X.Y.Z`:
 2. **Set both package versions to `X.Y.Z`.** Edit `packages/typescript/package.json`
    `"version"` to `X.Y.Z` (the Python version is derived from the tag, so it needs no
    file edit). The two must match or the npm publish step aborts.
-   Bump any docs that pin the version (`installation.md`, the guide, README) in the same
-   commit.
+   Public zero-install examples remain on `@latest` and require no release edit.
 
 3. **Run the full validation pass** from the
    [end-to-end testing runbook](e2e-testing.runbook.md): the local automated sweep
@@ -148,6 +144,15 @@ For each release of version `X.Y.Z`:
    and pass `--refresh` so uv does not serve a cached index that predates the publish
    (see runbook Phase 5).
 
+   Allow for publish propagation: PyPI updates its JSON API
+   (`pypi.org/pypi/softschema/json`) before the **simple index** uv resolves against
+   (`pypi.org/simple/softschema/`), so the first `uvx` run right after the workflow
+   turns green can fail with `no version of softschema==X.Y.Z` even though the release
+   is live. `--refresh` clears uv’s own cache but not PyPI’s CDN edge, so if that
+   happens, wait for the simple index to list the new `.whl`/`.tar.gz` and retry
+   (usually a few seconds).
+   npm propagates quickly and rarely shows this gap.
+
 <!-- This document follows common-doc-guidelines.md.
 See github.com/jlevy/practical-prose and review guidelines before editing.
 -->

{softschema-0.2.1 → softschema-0.3.0}/docs/softschema-guide.md

@@ -7,7 +7,7 @@ pattern.
 
 For the exact file format and validation rules, see
 [softschema Spec](softschema-spec.md).
-Two interchangeable implementations ship here, at exact behavioral parity: see
+Two interchangeable implementations share one portable contract: see
 [Python Package Design](softschema-python-design.md) and
 [TypeScript Package Design](softschema-typescript-design.md).
 
@@ -16,7 +16,7 @@ Two interchangeable implementations ship here, at exact behavioral parity: see
 To set up softschema in a repository with an agent, tell the agent:
 
 > Run `uvx softschema@latest --help` (for the Python implementation) or
-> `npx softschema@latest --help` (for the Node implementation) and follow the
+> `npx -y softschema@latest --help` (for the Node implementation) and follow the
 > instructions to set up softschema for this repo as a skill.
 
 The help output points the agent to the repo-local skill install command and the bundled
@@ -484,10 +484,10 @@ Pin softschema as a dev dependency so CI uses a known version:
 
 ```bash
 # Python
-uv add --dev softschema==0.2.0
+uv add --dev softschema
 
 # Node
-npm i -D softschema@0.2.0
+npm i -D softschema@latest
 ```
 
 Two checks belong in CI:
@@ -525,7 +525,7 @@ integration” section of [docs/development.md](development.md).
 
 Take an artifact that doesn’t fit the canonical shape and bring it in line.
 
-The canonical v0.2 shape is:
+The canonical shape is:
 
 - A `softschema:` block (the self-description quartet: `contract`, `schema`, `envelope`,
   `status`) plus a designated envelope key at the top level.
@@ -688,8 +688,8 @@ A few patterns help agents do the right thing:
 
 ## Relationship to the Packages
 
-Two interchangeable packages implement the language-neutral pattern at exact behavioral
-parity, Python/Pydantic and TypeScript/Zod.
+Two interchangeable packages implement the same language-neutral contract with
+Python/Pydantic and TypeScript/Zod.
 The Python public surface:
 
 - `Contract`: maps a contract ID to a Pydantic model and optional compiled JSON Schema.
@@ -700,8 +700,10 @@ The Python public surface:
 - `validate_values(values, model=..., schema=...)`: validates a values dict produced by
   any consumer (frontmatter, body-form runtime, structured-output adapter, hand-written
   fixture).
-- `compile_model(model_cls, out_path)`: emits a deterministic JSON Schema YAML file with
-  canonical-JSON hashing for drift checks.
+- `compile_model(model_cls, out_path, contract_id=..., schema_id=...)`: emits a
+  deterministic JSON Schema YAML file.
+  The required contract ID names the payload; the optional schema ID is a separate JSON
+  Schema resource URI.
 
 The TypeScript package mirrors this surface (`validateArtifact`, `validateValues`,
 `compileSchema`) with Zod models; both CLIs expose the same commands.