softschema 0.2.0

Minor release of the Python (PyPI) and TypeScript (npm) packages, advancing the spec and CLI from 0.1.x to self-describing artifacts. Both packages release together at exact behavioral parity, validated under Node (the published npm runtime), Bun, and Python 3.11–3.14.

The headline: an artifact now carries everything a validator needs in its own softschema: block, so softschema validate <file> works with zero flags — no --model, --schema, or --envelope required.

Breaking changes

• Compiled-schema error kinds renamed. schema_sidecar_missing → schema_missing and schema_sidecar_invalid → schema_invalid. The term "sidecar" is retired for the compiled schema throughout the spec, CLI output, and docs (it is reserved for a possible future sidematter-format alignment).
• Generated-section marker attribute renamed contract= → schema=. A softschema:generated marker now points at its compiled schema with schema="...path..."; a marker that still uses the old contract= attribute must be updated.
• Contract IDs are validated at metadata-parse time against the documented grammar, so a malformed contract is rejected up front rather than surfacing later.
• Non-mapping frontmatter is rejected on the TypeScript side as well, matching frontmatter-format (the Python implementation already did). A list or scalar where a mapping is expected is now a parse error on both engines.

New

• Self-describing artifacts. The softschema: block carries the full contract / schema / envelope / status quartet, and validate reads them from the document by default. --schema / --status / --envelope remain as explicit overrides.
• Host-over-document schema precedence with bounded resolution. A host-supplied schema wins over the document's own reference, and document-declared schema paths resolve relative-only (no escaping the artifact's directory).
• New docs topics example-artifact and example-schema print a copyable artifact and its compiled schema, so the quickstart runs from nothing installed and from an empty directory.

Docs and process

• Spec restructured terminology-first with a genuine worked example and the full design, and a consistent lowercase softschema naming sweep across live surfaces.
• Installed-user docs rework with a runnable-anywhere quickstart and a pinned-vs-zero-install consumption model.
• End-to-end testing runbook (docs/e2e-testing.runbook.md) codifies the full validation path — the automated sweep plus the clean-environment checks CI cannot run.
• PR-staged release process. Releases are now staged through a claude/release-X.Y.Z PR so CI validates the exact tree before the tag is cut; make format-check was fixed to run the full format pipeline before diffing (it previously reported false drift on a clean tree).

Testing and release safety

• 142 Python tests, 160 TypeScript tests with a coverage gate, the golden corpus on Python / Node / Bun, and a direct Python-vs-TypeScript byte-comparison job, all green.
• The publish workflow guards that the release tag matches both the derived Python version and packages/typescript/package.json before either registry is touched.

Full details in the repository's review and plan documents under docs/project/.