ossplate 0.1.1 → 0.1.3

package/README.md

@@ -1,5 +1,9 @@
 # Ossplate
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/stefdevscore/ossplate/dev/assets/illustrations/armour05platemail.png" alt="Ossplate armor" width="320">
+</p>
+
 `ossplate` helps you start and maintain a project that ships the same CLI through Rust, npm, and PyPI.
 
 Use it to:

package/package.json

@@ -39,5 +39,5 @@
     "test": "npm run build && node --test test/cli.test.js"
   },
   "type": "module",
-  "version": "0.1.1"
+  "version": "0.1.3"
 }

package/scaffold/.github/workflows/publish-npm.yml

@@ -44,8 +44,13 @@ jobs:
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
         run: |
+          logfile=$(mktemp)
+          cleanup() {
+            rm -f "$logfile"
+          }
+          trap cleanup EXIT
           set +e
-          npm publish --access public --provenance 2>&1 | tee npm-publish.log
+          npm publish --access public --provenance 2>&1 | tee "$logfile"
           status=${PIPESTATUS[0]}
           set -e
           if [ "$status" -eq 0 ]; then
@@ -56,7 +61,7 @@ jobs:
             echo "::error title=npm::OIDC publish failed and NPM_TOKEN is not configured."
             exit "$status"
           fi
-          if grep -qiE "already exists|cannot publish over|previously published" npm-publish.log; then
+          if grep -qiE "already exists|cannot publish over|previously published" "$logfile"; then
             echo "::notice title=npm::package version already exists; skipping."
             exit 0
           fi

package/scaffold/.github/workflows/publish.yml

@@ -74,23 +74,28 @@ jobs:
         env:
           CARGO_REGISTRY_TOKEN: ${{ steps.auth.outputs.token || secrets.CARGO_TOKEN }}
         run: |
+          logfile=$(mktemp)
+          cleanup() {
+            rm -f "$logfile"
+          }
+          trap cleanup EXIT
           if [ -n "${{ steps.auth.outputs.token }}" ]; then
             echo "::notice title=cargo::using crates.io OIDC token from trusted publishing."
           else
             echo "::notice title=cargo::OIDC token unavailable; falling back to CARGO_TOKEN secret."
           fi
           set +e
-          cargo publish 2>&1 | tee cargo-publish.log
+          cargo publish 2>&1 | tee "$logfile"
           status=${PIPESTATUS[0]}
           set -e
           if [ "$status" -eq 0 ]; then
             exit 0
           fi
-          if grep -q "status 429 Too Many Requests" cargo-publish.log; then
+          if grep -q "status 429 Too Many Requests" "$logfile"; then
             echo "::warning title=cargo::crates.io rate limit hit. Treating this publish attempt as non-blocking."
             exit 0
           fi
-          if grep -qi "already exists on crates.io index" cargo-publish.log; then
+          if grep -qi "already exists on crates.io index" "$logfile"; then
             echo "::notice title=cargo::crate version already exists; skipping."
             exit 0
           fi

package/scaffold/CONTRIBUTING.md

@@ -21,7 +21,12 @@ cargo run --manifest-path core-rs/Cargo.toml -- sync --check
 cargo run --manifest-path core-rs/Cargo.toml -- sync
 ```
 
-Release workflow guidance lives in [`docs/releases.md`](./docs/releases.md).
+Read this next:
+
+- [`docs/architecture.md`](./docs/architecture.md)
+- [`docs/testing.md`](./docs/testing.md)
+- [`docs/releases.md`](./docs/releases.md)
+- [`docs/adrs/0002-sync-owns-bounded-identity.md`](./docs/adrs/0002-sync-owns-bounded-identity.md)
 
 Current ownership model:
 

package/scaffold/README.md

@@ -4,7 +4,9 @@
 Build one project, ship it everywhere.
 <!-- ossplate:readme-identity:end -->
 
-![Ossplate chestplate](./assets/illustrations/chestplate.svg)
+<p align="center">
+  <img src="https://raw.githubusercontent.com/stefdevscore/ossplate/dev/assets/illustrations/armour05platemail.png" alt="Ossplate armor" width="360">
+</p>
 
 `ossplate` helps you start and maintain a project that ships the same CLI through Rust, npm, and PyPI.
 
@@ -69,6 +71,7 @@ The same command surface is available through the Rust binary and the packaged J
 ## Learn More
 
 - [Documentation](./docs/README.md)
+- [Adoption Guide](./docs/customizing-the-template.md)
 - [Testing Guide](./docs/testing.md)
 - [Release Guide](./docs/releases.md)
 - [Architecture](./docs/architecture.md)

package/scaffold/core-rs/Cargo.lock

@@ -158,7 +158,7 @@ checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe"
 
 [[package]]
 name = "ossplate"
-version = "0.1.1"
+version = "0.1.3"
 dependencies = [
  "anyhow",
  "clap",

package/scaffold/core-rs/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "ossplate"
-version = "0.1.1"
+version = "0.1.3"
 edition = "2021"
 authors = ["Stef <stefdevscore@github.com>"]
 description = "Build one project, ship it everywhere."

package/scaffold/core-rs/src/main.rs

@@ -1041,9 +1041,18 @@ fn validate_wrapper_readme(
 }
 
 fn render_wrapper_readme(_language: &str, config: &ToolConfig) -> String {
+    let image_url = github_raw_url(
+        &config.project.repository,
+        "dev",
+        "assets/illustrations/armour05platemail.png",
+    );
     format!(
         r#"# {name}
 
+<p align="center">
+  <img src="{image_url}" alt="{name} armor" width="320">
+</p>
+
 `{command}` helps you start and maintain a project that ships the same CLI through Rust, npm, and PyPI.
 
 Use it to:
@@ -1071,6 +1080,7 @@ Learn more:
 "#,
         name = config.project.name,
         command = config.packages.command,
+        image_url = image_url,
     )
 }
 
@@ -1081,6 +1091,15 @@ fn render_root_readme_identity(config: &ToolConfig) -> String {
     )
 }
 
+fn github_raw_url(repository: &str, branch: &str, path: &str) -> String {
+    let trimmed = repository.trim_end_matches('/');
+    if let Some(rest) = trimmed.strip_prefix("https://github.com/") {
+        format!("https://raw.githubusercontent.com/{rest}/{branch}/{path}")
+    } else {
+        format!("{trimmed}/{path}")
+    }
+}
+
 fn validate_workflow_name(
     path: &str,
     expected_name: &str,
@@ -1405,7 +1424,7 @@ mod tests {
             target.join("core-rs/Cargo.toml"),
             r#"[package]
 name = "bad-core"
-version = "0.1.1"
+version = "0.1.3"
 "#,
         )
         .unwrap();
@@ -1541,7 +1560,7 @@ command = "ossplate"
             root.join("core-rs/Cargo.toml"),
             r#"[package]
 name = "ossplate"
-version = "0.1.1"
+version = "0.1.3"
 edition = "2021"
 authors = ["Stef <stefdevscore@github.com>"]
 description = "A practical baseline for shipping one project across Cargo, npm, and PyPI without starting from scratch every time."

package/scaffold/docs/README.md

@@ -1,24 +1,16 @@
 # Documentation
 
-This docs area explains how to use `ossplate` as a real tool for validating, synchronizing, and now creating a multi-registry scaffold.
+`ossplate` is a tool for shipping one CLI across Cargo, npm, and PyPI without maintaining three separate implementations.
 
-## Start Here
+Start here:
 
-- [Customizing The Template](./customizing-the-template.md)
+- [Adoption Guide](./customizing-the-template.md)
 - [Architecture](./architecture.md)
-- [Testing Guide](./testing.md)
-- [Release Guide](./releases.md)
-- [Phase 1 Contract](./phase-1-contract.md)
-- [Upgrade Plan](./upgrade-plan.md)
-- `ossplate validate` checks owned metadata drift
-- `ossplate sync --check` verifies the repo is already synchronized
-- `ossplate create <target>` scaffolds a clean target directory and can apply identity overrides from flags
-- `ossplate init --path <dir>` hydrates an existing directory in place and can apply identity overrides from flags
+- [Testing](./testing.md)
+- [Releases](./releases.md)
 
-## What These Docs Cover
+Decision records:
 
-- the canonical config and command surface
-- the required rename and customization surface before first release
-- the layered testing and packaging workflow
-- the release operator flow and rerun-safe publish expectations
-- the phased plan for turning this tool into a broader scaffold product
+- [ADR 0001: Rust Core, Thin Wrappers](./adrs/0001-rust-core-thin-wrappers.md)
+- [ADR 0002: Sync Owns Bounded Identity Surfaces](./adrs/0002-sync-owns-bounded-identity.md)
+- [ADR 0003: Ship A Curated Scaffold Payload](./adrs/0003-curated-scaffold-payload.md)

package/scaffold/docs/adrs/0001-rust-core-thin-wrappers.md

@@ -0,0 +1,21 @@
+# ADR 0001: Rust Core, Thin Wrappers
+
+## Status
+
+Accepted
+
+## Context
+
+`ossplate` has to ship one command surface across Cargo, npm, and PyPI. Maintaining separate implementations would create drift quickly and make release verification harder.
+
+## Decision
+
+- Rust is the only product implementation.
+- JavaScript and Python packages are adapters that resolve the packaged binary and forward arguments.
+- Wrapper packages preserve stdout, stderr, and exit status from the Rust binary.
+
+## Consequences
+
+- New product behavior goes into `core-rs`.
+- JS and Python should stay small and operationally focused.
+- Parity testing can compare wrapper execution with direct Rust execution.

package/scaffold/docs/adrs/0002-sync-owns-bounded-identity.md

@@ -0,0 +1,31 @@
+# ADR 0002: Sync Owns Bounded Identity Surfaces
+
+## Status
+
+Accepted
+
+## Context
+
+`ossplate sync` must keep shared project identity aligned without becoming a destructive repo rewriter.
+
+## Decision
+
+`sync` owns only bounded, identity-bearing surfaces:
+
+- Rust, npm, and Python package metadata
+- wrapper package README content
+- the root README identity block between `ossplate:readme-identity` markers
+- workflow display names between `ossplate:workflow-name` markers
+
+`sync` does not own:
+
+- workflow logic
+- auth setup
+- arbitrary prose outside markers
+- docs that are not explicitly bounded
+
+## Consequences
+
+- Drift checks stay surgical.
+- Contributors can change most prose and workflow logic safely.
+- Any ownership expansion must be explicit and bounded first.

package/scaffold/docs/adrs/0003-curated-scaffold-payload.md

@@ -0,0 +1,21 @@
+# ADR 0003: Ship A Curated Scaffold Payload
+
+## Status
+
+Accepted
+
+## Context
+
+`create` and `init` need scaffold content even when `ossplate` is installed from npm or PyPI. A broad repo snapshot would work, but it would also ship tests, maintainer-only files, and accidental junk.
+
+## Decision
+
+- Installed wrapper artifacts ship a curated scaffold payload.
+- `scaffold-manifest.json` is the allowlist for that payload.
+- Artifact tests assert both required content and excluded content.
+
+## Consequences
+
+- Installed distributions can create and initialize projects end to end.
+- Package contents stay intentional.
+- Adding new scaffold files requires updating the manifest and tests.

package/scaffold/docs/architecture.md

@@ -0,0 +1,87 @@
+# Architecture
+
+`ossplate` is intentionally small. The design goal is simple: one real CLI, three distribution channels.
+
+## Runtime Shape
+
+- Rust in [`core-rs/`](../core-rs) is the product.
+- JavaScript in [`wrapper-js/`](../wrapper-js) is a package adapter.
+- Python in [`wrapper-py/`](../wrapper-py) is a package adapter.
+- The scaffold payload bundled into the wrappers is a distribution asset, not another implementation.
+
+The main commands are:
+
+- `version`
+- `validate`
+- `sync`
+- `create`
+- `init`
+
+## Responsibilities
+
+### Rust
+
+- command parsing
+- project identity loading from `ossplate.toml`
+- validation logic
+- metadata synchronization
+- scaffold creation and initialization
+
+Rust is the only layer that should know the semantics of project identity and owned metadata surfaces.
+
+### JavaScript and Python
+
+The wrappers own:
+
+- packaged binary lookup
+- platform/architecture target resolution
+- local binary override support
+- forwarding stdout, stderr, and exit code unchanged
+
+They should not implement separate business logic, metadata rules, or command behavior.
+
+### Scaffold Payload
+
+The scaffold payload owns the generated-project baseline:
+
+- manifests
+- docs
+- workflows
+- wrapper launchers
+- packaged binaries needed for installed-wrapper scaffold operations
+
+It is curated by manifest and shipped as part of the wrapper artifacts so `create` and `init` work from installed distributions.
+
+## Ownership Boundaries
+
+`ossplate sync` owns only bounded identity-bearing surfaces. The details are in the ADRs, but the practical rule is simple: if a surface is not explicitly bounded, `sync` should not rewrite it.
+
+Today that includes:
+
+- Cargo, npm, and Python metadata fields
+- wrapper package README identity
+- the root README identity block
+- workflow display names between `ossplate:workflow-name` markers
+
+It does not own:
+
+- workflow logic
+- auth setup
+- arbitrary prose outside bounded markers
+- separate wrapper-specific product behavior
+
+## Why It Scales
+
+If the tool grows, keep the current rules:
+
+- add product behavior in Rust
+- treat wrappers as delivery adapters
+- expand scaffold ownership only where the boundary is explicit and non-destructive
+
+That gives the project a clean path toward a fuller hexagonal structure without forcing that complexity into the current starter.
+
+## Related Decisions
+
+- [ADR 0001: Rust Core, Thin Wrappers](./adrs/0001-rust-core-thin-wrappers.md)
+- [ADR 0002: Sync Owns Bounded Identity Surfaces](./adrs/0002-sync-owns-bounded-identity.md)
+- [ADR 0003: Ship A Curated Scaffold Payload](./adrs/0003-curated-scaffold-payload.md)

package/scaffold/docs/customizing-the-template.md

@@ -1,6 +1,6 @@
-# Adopting The Scaffold
+# Adoption Guide
 
-Use this checklist after creating or cloning a scaffold managed by `ossplate`. The goal is to adopt the scaffold under your own project identity and then use the tool to keep owned metadata in sync.
+Use this guide after creating or cloning a project managed by `ossplate`. The goal is to adopt the scaffold under your own identity and then let the tool keep owned metadata aligned.
 
 ## Canonical Source Of Truth
 
@@ -22,15 +22,6 @@ It currently owns:
 
 `ossplate sync` rewrites the owned surfaces back into alignment.
 
-## Validation Policy
-
-- Template-source identities are allowed only when the repository is discussing `ossplate` itself.
-- Inherited identities are not allowed in shipping metadata or package-facing docs for an adopted project.
-- Command and package naming must be chosen intentionally before release.
-- Author, repository, and license fields must be set explicitly rather than inherited accidentally.
-
-The current validator follows this policy through the Rust core rather than a standalone JS rule engine.
-
 ## Required Identity Changes
 
 Replace these inherited defaults before reuse:
@@ -45,17 +36,6 @@ Replace these inherited defaults before reuse:
 | Author/email | `Stef <stefdevscore@github.com>` / `stefdevscore@github.com` | Rust, npm, Python metadata |
 | Package-facing scaffold branding | `ossplate` identity in wrapper docs | `wrapper-js/README.md`, `wrapper-py/README.md` |
 
-## Files To Review
-
-- `README.md`
-- `ossplate.toml`
-- `core-rs/Cargo.toml`
-- `wrapper-js/package.json`
-- `wrapper-js/README.md`
-- `wrapper-py/pyproject.toml`
-- `wrapper-py/README.md`
-- `.github/workflows/*.yml`
-
 ## What `ossplate validate` Enforces
 
 The tool reports:
@@ -81,15 +61,15 @@ The workflow files now expose a similarly bounded identity surface:
 
 `sync` owns only the display name between `ossplate:workflow-name` markers. Trigger logic, jobs, auth, and shell steps remain manual.
 
-## First-Run Sequence After Cloning
+## First Run
 
 1. Either update `ossplate.toml` directly or use `create` / `init` with identity flags.
 2. Run `cargo run --manifest-path core-rs/Cargo.toml -- sync`.
 3. Run `cargo run --manifest-path core-rs/Cargo.toml -- validate`.
-4. Run the layered verification flow from [Testing Guide](./testing.md).
+4. Run the verification flow from [Testing](./testing.md).
 5. Only then expand product code or publish configuration.
 
-## Create Workflow
+## Create A New Project
 
 To scaffold a fresh target from the current template tree:
 
@@ -107,9 +87,9 @@ cargo run --manifest-path core-rs/Cargo.toml -- create ../my-new-project \
 
 That copies the curated scaffold payload into the target directory, applies any identity overrides to `ossplate.toml`, then runs `sync` on the new target.
 
-The packaged scaffold intentionally excludes wrapper test suites and maintainer-only validation scripts. Generated projects get the delivery baseline and operator docs, not the source repo's internal test harness.
+The packaged scaffold intentionally excludes wrapper test suites and maintainer-only utilities. Generated projects get the delivery baseline and operator docs, not the source repo's internal harness.
 
-## Init Workflow
+## Adopt An Existing Directory
 
 To hydrate an existing directory in place:
 
@@ -122,7 +102,7 @@ cargo run --manifest-path core-rs/Cargo.toml -- init \
 
 `init` ensures the expected scaffold layout exists, copies any missing scaffold files, applies any requested identity overrides, and then runs `sync` so owned metadata matches `ossplate.toml`.
 
-## Supported Identity Flags
+## Identity Flags
 
 - `--name`
 - `--description`
@@ -135,10 +115,7 @@ cargo run --manifest-path core-rs/Cargo.toml -- init \
 - `--python-package`
 - `--command`
 
-## Why This Exists
-
-This tool is trying to optimize for a real delivery baseline:
+## Related Decisions
 
-- CI should fail before inherited identity reaches a release path.
-- package metadata should not be inherited by accident
-- future phases can add richer scaffold creation and maintenance without first cleaning up metadata drift
+- [ADR 0002: Sync Owns Bounded Identity Surfaces](./adrs/0002-sync-owns-bounded-identity.md)
+- [ADR 0003: Ship A Curated Scaffold Payload](./adrs/0003-curated-scaffold-payload.md)

package/scaffold/docs/releases.md

@@ -0,0 +1,71 @@
+# Releases
+
+Use this guide when cutting a new `ossplate` release.
+
+## Current Registry Setup
+
+- PyPI publishes from [`.github/workflows/publish.yml`](../.github/workflows/publish.yml) via GitHub OIDC trusted publishing.
+- crates.io publishes from [`.github/workflows/publish.yml`](../.github/workflows/publish.yml) via OIDC trusted publishing with `CARGO_TOKEN` fallback.
+- npm publishes from [`.github/workflows/publish-npm.yml`](../.github/workflows/publish-npm.yml) via OIDC trusted publishing with `NPM_TOKEN` fallback.
+
+## Before Release
+
+Run the full gate before creating a release:
+
+```bash
+./scripts/verify.sh
+```
+
+Optional local packaging confidence checks:
+
+```bash
+cargo package --manifest-path core-rs/Cargo.toml
+cargo publish --manifest-path core-rs/Cargo.toml --dry-run
+cd wrapper-js && npm pack --dry-run
+cd ../wrapper-py && python -m build --wheel
+```
+
+## Versioning
+
+Keep the registry versions aligned across:
+
+- [`core-rs/Cargo.toml`](../core-rs/Cargo.toml)
+- [`wrapper-js/package.json`](../wrapper-js/package.json)
+- [`wrapper-py/pyproject.toml`](../wrapper-py/pyproject.toml)
+
+After updating versions, rerun:
+
+```bash
+./scripts/verify.sh
+```
+
+## Release Flow
+
+1. Commit the version bump and any release notes.
+2. Push `dev`.
+3. Create a GitHub release that targets `dev`, or manually dispatch the publish workflows.
+4. Monitor:
+   - [`.github/workflows/publish.yml`](../.github/workflows/publish.yml)
+   - [`.github/workflows/publish-npm.yml`](../.github/workflows/publish-npm.yml)
+
+## Rerun Behavior
+
+The publish jobs are intentionally rerun-safe.
+
+- Cargo checks whether the crate version already exists before attempting publish.
+- npm checks whether the package version already exists before attempting publish.
+- PyPI uses `skip-existing: true`.
+
+So a second run for the same version should usually succeed by skipping work rather than failing destructively.
+
+## Current Published Names
+
+- crates.io: `ossplate`
+- npm: `ossplate`
+- PyPI: `ossplate`
+- CLI: `ossplate`
+
+## Maintenance
+
+- Refresh GitHub Actions dependencies before the Node 20 runner deprecation becomes a problem.
+- Keep the release auth docs aligned with real registry configuration whenever trusted publishing or token fallback changes.

package/scaffold/docs/testing.md

@@ -1,8 +1,8 @@
-# Testing Guide
+# Testing
 
 `ossplate` uses layered verification so the scaffold stays usable as both a source checkout and an installed wrapper distribution.
 
-## Default Layers
+## Layers
 
 ### Smoke
 
@@ -39,7 +39,7 @@ Artifact assertions are part of the required packaging layer:
 - Python wheel content must include the curated scaffold files from `scaffold-manifest.json`
 - Python wheel content must exclude wrapper test files and repo-only validation scripts
 
-## Recommended Local Order
+## Default Local Flow
 
 Default path:
 
@@ -59,7 +59,7 @@ Underlying command order:
 8. `PYTHONPATH=src python3 -m unittest discover -s tests -p 'test_*.py'`
 9. `python -m build --wheel`
 
-## CI Expectations
+## CI
 
 CI currently enforces:
 
@@ -68,6 +68,6 @@ CI currently enforces:
 - JS build, tests, and package dry-run
 - Python tests and wheel build
 
-The current artifact tests are the required release-confidence floor. Future phases can add broader platform coverage or slower end-to-end suites without changing the basic layered model.
+The current artifact tests are the required release-confidence floor.
 
 For release-specific operator steps, version bumps, and rerun-safe publish expectations, see [`docs/releases.md`](./releases.md).

package/scaffold/wrapper-js/README.md

@@ -1,5 +1,9 @@
 # Ossplate
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/stefdevscore/ossplate/dev/assets/illustrations/armour05platemail.png" alt="Ossplate armor" width="320">
+</p>
+
 `ossplate` helps you start and maintain a project that ships the same CLI through Rust, npm, and PyPI.
 
 Use it to:

package/scaffold/wrapper-js/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "ossplate",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "ossplate",
-      "version": "0.1.1",
+      "version": "0.1.3",
       "license": "Unlicense",
       "bin": {
         "ossplate": "bin/ossplate.js"

package/scaffold/wrapper-js/package.json

@@ -39,5 +39,5 @@
     "test": "npm run build && node --test test/cli.test.js"
   },
   "type": "module",
-  "version": "0.1.1"
+  "version": "0.1.3"
 }

package/scaffold/wrapper-py/README.md

@@ -1,5 +1,9 @@
 # Ossplate
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/stefdevscore/ossplate/dev/assets/illustrations/armour05platemail.png" alt="Ossplate armor" width="320">
+</p>
+
 `ossplate` helps you start and maintain a project that ships the same CLI through Rust, npm, and PyPI.
 
 Use it to:

package/scaffold/wrapper-py/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ossplate"
-version = "0.1.1"
+version = "0.1.3"
 description = "Build one project, ship it everywhere."
 readme = "README.md"
 requires-python = ">=3.10"

package/scaffold/assets/illustrations/chestplate.svg

@@ -1,46 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 720 420" role="img" aria-labelledby="title desc">
-  <title id="title">Ossplate chestplate illustration</title>
-  <desc id="desc">A bronze chestplate with shoulder guards on a warm background.</desc>
-  <defs>
-    <linearGradient id="bg" x1="0%" y1="0%" x2="100%" y2="100%">
-      <stop offset="0%" stop-color="#f7ecdd"/>
-      <stop offset="100%" stop-color="#dcb88b"/>
-    </linearGradient>
-    <linearGradient id="metal" x1="0%" y1="0%" x2="0%" y2="100%">
-      <stop offset="0%" stop-color="#ddaf68"/>
-      <stop offset="50%" stop-color="#b77735"/>
-      <stop offset="100%" stop-color="#7b491c"/>
-    </linearGradient>
-    <linearGradient id="rim" x1="0%" y1="0%" x2="100%" y2="100%">
-      <stop offset="0%" stop-color="#fff0bf"/>
-      <stop offset="100%" stop-color="#a05d24"/>
-    </linearGradient>
-    <linearGradient id="highlight" x1="0%" y1="0%" x2="100%" y2="100%">
-      <stop offset="0%" stop-color="#fff8de" stop-opacity="0.95"/>
-      <stop offset="100%" stop-color="#fff8de" stop-opacity="0"/>
-    </linearGradient>
-    <filter id="shadow" x="-20%" y="-20%" width="140%" height="160%">
-      <feDropShadow dx="0" dy="16" stdDeviation="12" flood-color="#673d18" flood-opacity="0.28"/>
-    </filter>
-  </defs>
-
-  <rect width="720" height="420" fill="url(#bg)"/>
-  <circle cx="110" cy="84" r="58" fill="#fff7de" opacity="0.4"/>
-  <circle cx="607" cy="314" r="76" fill="#a86e33" opacity="0.12"/>
-
-  <g filter="url(#shadow)" transform="translate(150 28)">
-    <path d="M151 46c12-18 27-29 59-34 16-2 42-3 59-3s43 1 59 3c32 5 47 16 59 34l24 35c7 10 4 24-6 31l-22 16c-8 6-19 7-29 2l-27-13v90c0 60-26 102-58 129-32 26-64 39-91 45-27-6-59-19-91-45-32-27-58-69-58-129v-90l-27 13c-10 5-21 4-29-2l-22-16c-10-7-13-21-6-31z" fill="url(#metal)"/>
-    <path d="M151 46c12-18 27-29 59-34 16-2 42-3 59-3s43 1 59 3c32 5 47 16 59 34l24 35c7 10 4 24-6 31l-22 16c-8 6-19 7-29 2l-27-13v90c0 60-26 102-58 129-32 26-64 39-91 45-27-6-59-19-91-45-32-27-58-69-58-129v-90l-27 13c-10 5-21 4-29-2l-22-16c-10-7-13-21-6-31z" fill="none" stroke="#6b4118" stroke-width="10" stroke-linejoin="round"/>
-    <path d="M210 52c11-14 26-20 44-22 15-2 29-2 46-2s31 0 46 2c18 2 33 8 44 22l15 20c-41 18-92 27-105 29-13-2-64-11-105-29z" fill="#c78741" opacity="0.88"/>
-    <path d="M126 74l32 16c10 5 21 4 30-2l20-13c18 9 43 16 72 20v204c-56-15-121-61-121-158V93c0-8-12-13-33-19z" fill="#845022" opacity="0.34"/>
-    <path d="M474 74l-32 16c-10 5-21 4-30-2l-20-13c-18 9-43 16-72 20v204c56-15 121-61 121-158V93c0-8 12-13 33-19z" fill="#f0c27a" opacity="0.2"/>
-    <path d="M300 92v214" stroke="#6b4118" stroke-width="8" stroke-linecap="round" opacity="0.82"/>
-    <path d="M196 134c29 12 65 18 104 18s75-6 104-18" stroke="#6b4118" stroke-width="7" stroke-linecap="round" opacity="0.72"/>
-    <path d="M206 215c24 9 56 14 94 14s70-5 94-14" stroke="#6b4118" stroke-width="6" stroke-linecap="round" opacity="0.62"/>
-    <path d="M235 42c19 10 40 16 65 19-13 10-23 24-29 41-25-4-48-12-68-25 7-16 17-27 32-35z" fill="url(#highlight)" opacity="0.72"/>
-    <path d="M300 61c25-3 46-9 65-19 15 8 25 19 32 35-20 13-43 21-68 25-6-17-16-31-29-41z" fill="url(#highlight)" opacity="0.5"/>
-    <path d="M147 62l-41 58c-5 7-3 17 4 22l18 13c5 4 12 4 18 1l41-19-9-53c-2-11-14-21-31-22z" fill="url(#rim)" opacity="0.95"/>
-    <path d="M453 62l41 58c5 7 3 17-4 22l-18 13c-5 4-12 4-18 1l-41-19 9-53c2-11 14-21 31-22z" fill="url(#rim)" opacity="0.95"/>
-    <path d="M214 310c26 14 56 23 86 28 30-5 60-14 86-28" stroke="#f3d39a" stroke-width="6" stroke-linecap="round" opacity="0.45"/>
-  </g>
-</svg>

package/scaffold/docs/phase-1-contract.md

@@ -1,52 +0,0 @@
-# Phase 1 Contract
-
-Phase 1 establishes a single canonical CLI surface in the Rust core. The JavaScript and Python packages are wrappers that delegate to that binary rather than implementing separate behavior.
-
-## Canonical Commands
-
-- `version`
-  returns JSON with the tool identity and package version
-- `validate [--path <dir>] [--json]`
-  returns validation results for owned metadata surfaces
-- `sync [--path <dir>] [--check]`
-  rewrites or checks owned metadata surfaces against the canonical project identity
-- `create <target>`
-  copies the curated scaffold payload into a clean target directory, applies optional identity overrides, and synchronizes the owned metadata surfaces there
-- `init [--path <dir>]`
-  hydrates an existing directory with the expected scaffold layout, applies optional identity overrides, and then synchronizes owned metadata in place
-
-Both commands are available from source checkouts and installed wrapper artifacts that include the staged scaffold payload.
-
-## Expected Output Shapes
-
-```json
-{"tool":"ossplate","version":"0.1.0"}
-{"ok":true,"issues":[]}
-```
-
-## Wrapper Model
-
-- Rust is the source of truth for command parsing and output.
-- JavaScript and Python are adapter layers that resolve a packaged binary and forward arguments unchanged.
-- Wrappers preserve stdout, stderr, and exit status from the core binary.
-
-## Local Development Override
-
-Both wrappers support `OSSPLATE_BINARY` to bypass packaged binary lookup during local development and parity testing.
-
-`create` and `init` also honor `OSSPLATE_TEMPLATE_ROOT` when the template source needs to be overridden explicitly.
-
-## Packaged Binary Layout
-
-Wrappers expect binaries under:
-
-```text
-bin/<target>/<executable>
-```
-
-Supported target identifiers are aligned across wrappers:
-
-- `darwin-arm64`
-- `darwin-x64`
-- `linux-x64`
-- `win32-x64`

package/scaffold/docs/upgrade-plan.md

@@ -1,88 +0,0 @@
-# Ossplate Roadmap
-
-## Current State
-
-`ossplate` is no longer a placeholder scaffold. It now ships as a real multi-registry tool with:
-
-- a canonical Rust CLI
-- thin npm and Python wrappers
-- real `validate`, `sync`, `create`, and `init` commands
-- curated scaffold payloads in installed wrapper artifacts
-- CI quality gates across Rust, JS, and Python
-- OIDC-first publishing for PyPI, Cargo, and npm, with token fallbacks where configured
-
-Published names are aligned as:
-
-- crates.io: `ossplate`
-- npm: `ossplate`
-- PyPI: `ossplate`
-- CLI: `ossplate`
-
-## Completed
-
-### Foundation
-
-- Placeholder identity validation is wired into CI.
-- `ossplate.toml` is the canonical identity source.
-- Root docs, testing docs, customization docs, and release docs now exist.
-
-### Product Surface
-
-- Rust is the only source of product logic.
-- JS and Python are thin wrappers around the packaged binary.
-- The command surface is now real:
-  `version`, `validate`, `sync`, `create`, `init`.
-
-### Packaging And Artifact Reality
-
-- Installed npm and Python artifacts carry the scaffold payload required by `create` and `init`.
-- Scaffold payload staging is curated by manifest rather than broad repo-copy behavior.
-- Artifact tests verify required content and exclude known non-shipping content.
-
-### Quality Gates
-
-- CI enforces Rust format, clippy, and tests.
-- CI enforces JS build, tests, and package dry-run.
-- CI enforces Python tests and wheel build.
-- Wrapper parity and installed-artifact smoke paths are exercised.
-- `./scripts/verify.sh` mirrors the local gate.
-
-### Publishing
-
-- Publish flows are rerun-safe.
-- PyPI uses OIDC.
-- Cargo uses OIDC with `CARGO_TOKEN` fallback.
-- npm uses OIDC with `NPM_TOKEN` fallback.
-- The release operator flow is documented in [`docs/releases.md`](./releases.md).
-
-## Remaining Priorities
-
-## P1
-
-- Expand `sync` ownership carefully into a few more identity-only surfaces where bounded ownership is safe.
-- Improve `validate` and `sync --check` output further if field-level drift becomes hard to read at scale.
-- Add a short architecture note describing the current boundary:
-  Rust core as product logic, JS/Python as adapters, scaffold payload as distribution asset.
-
-## P2
-
-- Add optional guidance for generated projects that need browser-based live end-to-end tests.
-- Add examples of failure triage for packaging, publish, and parity regressions.
-- Tighten workflow/docs ownership boundaries further if more fields become sync-managed.
-
-## P3
-
-- Add architecture-shell guidance for teams that want to scale generated projects into a fuller hexagonal layout.
-- Add ADR guidance if the scaffold evolves into a broader product platform.
-
-## Release Maintenance
-
-- Refresh GitHub Actions dependencies ahead of the Node 20 runner deprecation.
-- Keep trusted publishing and token fallback documentation aligned with real registry configuration.
-- Keep release-version bumps aligned across Cargo, npm, and PyPI metadata.
-
-## Suggested Next Work
-
-1. Decide whether `sync` should own any additional identity-only fields beyond the current bounded set.
-2. Improve `validate` and `sync --check` if larger repos need richer drift output.
-3. Add optional browser-e2e guidance for generated projects that include a UI.