ossplate 0.1.0 → 0.1.2

package/README.md

@@ -1,7 +1,28 @@
-# JavaScript Wrapper For Ossplate
+# Ossplate
 
-This package is the JavaScript wrapper surface for Ossplate.
+![Ossplate armor](https://raw.githubusercontent.com/stefdevscore/ossplate/dev/assets/illustrations/armour05platemail.png)
 
-It delegates to the canonical Rust binary instead of implementing its own CLI behavior.
+`ossplate` helps you start and maintain a project that ships the same CLI through Rust, npm, and PyPI.
 
-Use `OSSPLATE_BINARY` during local development to point the wrapper at a specific binary.
+Use it to:
+
+- create a new scaffolded project
+- initialize an existing directory
+- validate project identity and metadata
+- keep owned files in sync
+
+Common commands:
+
+```bash
+ossplate version
+ossplate create <target>
+ossplate init --path <dir>
+ossplate validate
+ossplate sync --check
+```
+
+Learn more:
+
+- [Main documentation](../docs/README.md)
+- [Testing guide](../docs/testing.md)
+- [Architecture](../docs/architecture.md)

package/package.json

@@ -3,7 +3,7 @@
   "bin": {
     "ossplate": "bin/ossplate.js"
   },
-  "description": "A practical baseline for shipping one project across Cargo, npm, and PyPI without starting from scratch every time.",
+  "description": "Build one project, ship it everywhere.",
   "devDependencies": {
     "@types/node": "^24.6.0",
     "typescript": "^5.9.3"
@@ -39,5 +39,5 @@
     "test": "npm run build && node --test test/cli.test.js"
   },
   "type": "module",
-  "version": "0.1.0"
+  "version": "0.1.2"
 }

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

@@ -38,8 +38,32 @@ jobs:
       - if: steps.published.outputs.already != 'true'
         run: npm ci
         working-directory: ./wrapper-js
-      - if: steps.published.outputs.already != 'true'
-        run: npm publish --access public
+      - name: Publish to npm
+        if: steps.published.outputs.already != 'true'
         working-directory: ./wrapper-js
         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 "$logfile"
+          status=${PIPESTATUS[0]}
+          set -e
+          if [ "$status" -eq 0 ]; then
+            echo "::notice title=npm::published with OIDC trusted publishing."
+            exit 0
+          fi
+          if [ -z "${NODE_AUTH_TOKEN:-}" ]; then
+            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" "$logfile"; then
+            echo "::notice title=npm::package version already exists; skipping."
+            exit 0
+          fi
+          echo "::warning title=npm::OIDC publish failed; retrying with NPM_TOKEN fallback."
+          npm publish --access public

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,6 +21,8 @@ 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).
+
 Current ownership model:
 
 - `ossplate.toml` is the canonical identity source

package/scaffold/README.md

@@ -1,36 +1,32 @@
 <!-- ossplate:readme-identity:start -->
 # Ossplate
 
-A practical baseline for shipping one project across Cargo, npm, and PyPI without starting from scratch every time.
+Build one project, ship it everywhere.
 <!-- ossplate:readme-identity:end -->
 
-## What This Tool Gives You
+![Ossplate armor](https://raw.githubusercontent.com/stefdevscore/ossplate/dev/assets/illustrations/armour05platemail.png)
 
-- a canonical Rust CLI in [`core-rs/`](./core-rs)
-- a thin npm wrapper in [`wrapper-js/`](./wrapper-js)
-- a thin Python wrapper in [`wrapper-py/`](./wrapper-py)
-- normal `push` / `pull_request` CI
-- rerun-safe publish workflows for npm, PyPI, and Cargo
-- setup and upgrade docs in [`docs/`](./docs/README.md)
+`ossplate` helps you start and maintain a project that ships the same CLI through Rust, npm, and PyPI.
 
-## Philosophy
+It gives you a working baseline with:
 
-This project is intentionally small.
+- one real core CLI
+- thin JavaScript and Python wrappers
+- release-ready workflows for Cargo, npm, and PyPI
+- a scaffold you can create, adopt, and keep in sync
 
-It exists to validate and synchronize the shared identity of a multi-registry OSS scaffold before broader scaffolding features are added.
+## What It Does
 
-## Core Commands
+Use `ossplate` when you want a single command-line tool to exist cleanly in multiple ecosystems without maintaining three separate implementations.
 
-```bash
-cargo run --manifest-path core-rs/Cargo.toml -- validate
-cargo run --manifest-path core-rs/Cargo.toml -- sync --check
-cargo run --manifest-path core-rs/Cargo.toml -- create ../my-new-project
-cargo run --manifest-path core-rs/Cargo.toml -- init --path ../existing-project
-```
+It can:
 
-Wrapper installs expose the same command surface as `ossplate`.
+- create a new scaffolded project
+- initialize an existing directory with the expected structure
+- validate project identity and metadata
+- synchronize the files it owns
 
-`create` and `init` now work from packaged wrapper artifacts as well as a source checkout. Installed wrappers carry a curated scaffold payload rather than a broad repo snapshot. Use flags to set the project identity during scaffold creation instead of editing `ossplate.toml` by hand first:
+## Quick Start
 
 ```bash
 cargo run --manifest-path core-rs/Cargo.toml -- create ../my-new-project \
@@ -44,29 +40,38 @@ cargo run --manifest-path core-rs/Cargo.toml -- create ../my-new-project \
   --command "my-project"
 ```
 
-## Local Verify
+Then check that everything is aligned:
 
-Run the full local verification flow with:
+```bash
+cargo run --manifest-path core-rs/Cargo.toml -- validate
+cargo run --manifest-path core-rs/Cargo.toml -- sync --check
+```
+
+## Core Commands
 
 ```bash
-./scripts/verify.sh
+ossplate version
+ossplate create <target>
+ossplate init --path <dir>
+ossplate validate
+ossplate sync --check
 ```
 
-This is the recommended local mirror of the CI gate.
+The same command surface is available through the Rust binary and the packaged JS/Python wrappers.
 
-## Verification
+## Why It’s Useful
 
-- local workflow and layered testing guidance live in [docs/testing.md](./docs/testing.md)
-- contributor workflow lives in [CONTRIBUTING.md](./CONTRIBUTING.md)
-- `ossplate validate` reports owned metadata drift
-- `ossplate sync --check` fails if owned metadata would be rewritten
-- JS and Python artifact tests prove installed distributions can run `version`, `create`, and `validate`
+- You keep one source of truth for CLI behavior.
+- You avoid drift between Rust, npm, and PyPI releases.
+- You get a real scaffold instead of a fake demo project.
+- You can publish with modern registry workflows instead of assembling release plumbing from scratch.
 
-## Release Auth
+## Learn More
 
-- PyPI publishes from [`.github/workflows/publish.yml`](./.github/workflows/publish.yml) via GitHub OIDC trusted publishing
-- Cargo publishes from [`.github/workflows/publish.yml`](./.github/workflows/publish.yml) via OIDC trusted publishing with `secrets.CARGO_TOKEN` as fallback
-- npm publishes from [`.github/workflows/publish-npm.yml`](./.github/workflows/publish-npm.yml) with `secrets.NPM_TOKEN`
+- [Documentation](./docs/README.md)
+- [Testing Guide](./docs/testing.md)
+- [Release Guide](./docs/releases.md)
+- [Architecture](./docs/architecture.md)
 
 ## License
 

package/scaffold/core-rs/Cargo.lock

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

package/scaffold/core-rs/Cargo.toml

@@ -1,9 +1,9 @@
 [package]
 name = "ossplate"
-version = "0.1.0"
+version = "0.1.2"
 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."
+description = "Build one project, ship it everywhere."
 license = "Unlicense"
 readme = "../README.md"
 repository = "https://github.com/stefdevscore/ossplate"

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

@@ -1040,18 +1040,45 @@ fn validate_wrapper_readme(
     }
 }
 
-fn render_wrapper_readme(language: &str, config: &ToolConfig) -> String {
+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#"# {language} Wrapper For {name}
+        r#"# {name}
+
+![{name} armor]({image_url})
+
+`{command}` helps you start and maintain a project that ships the same CLI through Rust, npm, and PyPI.
+
+Use it to:
+
+- create a new scaffolded project
+- initialize an existing directory
+- validate project identity and metadata
+- keep owned files in sync
+
+Common commands:
 
-This package is the {language} wrapper surface for {name}.
+```bash
+{command} version
+{command} create <target>
+{command} init --path <dir>
+{command} validate
+{command} sync --check
+```
 
-It delegates to the canonical Rust binary instead of implementing its own CLI behavior.
+Learn more:
 
-Use `OSSPLATE_BINARY` during local development to point the wrapper at a specific binary.
+- [Main documentation](../docs/README.md)
+- [Testing guide](../docs/testing.md)
+- [Architecture](../docs/architecture.md)
 "#,
-        language = language,
         name = config.project.name,
+        command = config.packages.command,
+        image_url = image_url,
     )
 }
 
@@ -1062,6 +1089,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,
@@ -1266,7 +1302,7 @@ mod tests {
         let root = make_fixture_root();
         fs::write(
             root.join("wrapper-js/package.json"),
-            "{\n  \"name\": \"bad\",\n  \"description\": \"A practical baseline for shipping one project across Cargo, npm, and PyPI without starting from scratch every time.\",\n  \"bin\": { \"ossplate\": \"bin/ossplate.js\" },\n  \"author\": \"Stef <stefdevscore@github.com>\",\n  \"license\": \"Unlicense\",\n  \"repository\": { \"url\": \"https://github.com/stefdevscore/ossplate\" }\n}\n",
+            "{\n  \"name\": \"bad\",\n  \"description\": \"Build one project, ship it everywhere.\",\n  \"bin\": { \"ossplate\": \"bin/ossplate.js\" },\n  \"author\": \"Stef <stefdevscore@github.com>\",\n  \"license\": \"Unlicense\",\n  \"repository\": { \"url\": \"https://github.com/stefdevscore/ossplate\" }\n}\n",
         )
         .unwrap();
         let output = validate_repo(&root).unwrap();
@@ -1386,7 +1422,7 @@ mod tests {
             target.join("core-rs/Cargo.toml"),
             r#"[package]
 name = "bad-core"
-version = "0.1.0"
+version = "0.1.2"
 "#,
         )
         .unwrap();
@@ -1440,7 +1476,7 @@ version = "0.1.0"
         fs::write(
             root.join("README.md"),
             original.replace(
-                "A practical baseline for shipping one project",
+                "Build one project, ship it everywhere",
                 "Changed identity text",
             ),
         )
@@ -1449,7 +1485,7 @@ version = "0.1.0"
         sync_repo(&root, false).unwrap();
         let synced = fs::read_to_string(root.join("README.md")).unwrap();
         assert!(synced.contains("## What This Tool Gives You"));
-        assert!(synced.contains("A practical baseline for shipping one project"));
+        assert!(synced.contains("Build one project, ship it everywhere"));
     }
 
     #[test]
@@ -1499,7 +1535,7 @@ version = "0.1.0"
         let config = r#"[project]
 name = "Ossplate"
 slug = "ossplate"
-description = "A practical baseline for shipping one project across Cargo, npm, and PyPI without starting from scratch every time."
+description = "Build one project, ship it everywhere."
 repository = "https://github.com/stefdevscore/ossplate"
 license = "Unlicense"
 
@@ -1522,7 +1558,7 @@ command = "ossplate"
             root.join("core-rs/Cargo.toml"),
             r#"[package]
 name = "ossplate"
-version = "0.1.0"
+version = "0.1.2"
 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."
@@ -1535,14 +1571,14 @@ homepage = "https://github.com/stefdevscore/ossplate"
         .unwrap();
         fs::write(
             root.join("wrapper-js/package.json"),
-            "{\n  \"name\": \"ossplate\",\n  \"description\": \"A practical baseline for shipping one project across Cargo, npm, and PyPI without starting from scratch every time.\",\n  \"bin\": { \"ossplate\": \"bin/ossplate.js\" },\n  \"author\": \"Stef <stefdevscore@github.com>\",\n  \"license\": \"Unlicense\",\n  \"repository\": { \"url\": \"https://github.com/stefdevscore/ossplate\" }\n}\n",
+            "{\n  \"name\": \"ossplate\",\n  \"description\": \"Build one project, ship it everywhere.\",\n  \"bin\": { \"ossplate\": \"bin/ossplate.js\" },\n  \"author\": \"Stef <stefdevscore@github.com>\",\n  \"license\": \"Unlicense\",\n  \"repository\": { \"url\": \"https://github.com/stefdevscore/ossplate\" }\n}\n",
         )
         .unwrap();
         fs::write(
             root.join("wrapper-py/pyproject.toml"),
             r#"[project]
 name = "ossplate"
-description = "A practical baseline for shipping one project across Cargo, npm, and PyPI without starting from scratch every time."
+description = "Build one project, ship it everywhere."
 license = { text = "Unlicense" }
 authors = [
   { name = "Stef", email = "stefdevscore@github.com" }

package/scaffold/docs/README.md

@@ -5,7 +5,9 @@ This docs area explains how to use `ossplate` as a real tool for validating, syn
 ## Start Here
 
 - [Customizing The Template](./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
@@ -18,4 +20,5 @@ This docs area explains how to use `ossplate` as a real tool for validating, syn
 - 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

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

@@ -1,6 +1,6 @@
-# Customizing The Template
+# Adopting The Scaffold
 
-Use this checklist after creating or cloning a scaffold managed by `ossplate`. The goal is to replace inherited identity deliberately and then use the tool to keep owned metadata in sync.
+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.
 
 ## Canonical Source Of Truth
 
@@ -24,18 +24,18 @@ It currently owns:
 
 ## Validation Policy
 
-- Placeholder identities are allowed only when the repository is discussing the template itself.
-- Placeholder identities are not allowed in shipping metadata or package-facing docs for an adopted project.
+- 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 Renames
+## Required Identity Changes
 
-Replace these defaults before reuse:
+Replace these inherited defaults before reuse:
 
-| Surface | Current placeholder | Where it lives |
+| Surface | Current scaffold value | Where it lives |
 | --- | --- | --- |
 | Rust crate name | `ossplate` | `core-rs/Cargo.toml` |
 | npm package name | `ossplate` | `wrapper-js/package.json` |
@@ -43,7 +43,7 @@ Replace these defaults before reuse:
 | CLI command | `ossplate` | `ossplate.toml`, `wrapper-js/package.json`, `wrapper-py/pyproject.toml` |
 | Repository URL | `https://github.com/stefdevscore/ossplate` | Rust, npm, Python metadata |
 | Author/email | `Stef <stefdevscore@github.com>` / `stefdevscore@github.com` | Rust, npm, Python metadata |
-| Package-facing template branding | `OSS template`, `template` identity in wrapper docs | `wrapper-js/README.md`, `wrapper-py/README.md` |
+| Package-facing scaffold branding | `ossplate` identity in wrapper docs | `wrapper-js/README.md`, `wrapper-py/README.md` |
 
 ## Files To Review
 
@@ -139,6 +139,6 @@ cargo run --manifest-path core-rs/Cargo.toml -- init \
 
 This tool is trying to optimize for a real delivery baseline:
 
-- CI should fail before placeholder identity reaches a release path.
+- 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

package/scaffold/docs/testing.md

@@ -69,3 +69,5 @@ CI currently enforces:
 - 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.
+
+For release-specific operator steps, version bumps, and rerun-safe publish expectations, see [`docs/releases.md`](./releases.md).

package/scaffold/docs/upgrade-plan.md

@@ -1,251 +1,88 @@
-# Ossplate Upgrade Plan
+# Ossplate Roadmap
 
-## Goal
-
-Turn `ossplate` from a minimal multi-registry demo into a production-ready scaffold tool with:
-
-- one canonical core program
-- real wrapper parity across Rust, TypeScript/JavaScript, and Python
-- robust CI and publish workflows with explicit auth fallbacks
-- layered testing guidance and enforcement
-- a structure that can scale toward a hexagonal architecture shell
-
-The product behavior is now real in the core maintenance and scaffold paths. Remaining work is about hardening, ergonomics, and release scale.
-
-## Operating Principles
-
-- Keep one source of truth for CLI behavior and output contracts.
-- Prefer thin wrappers over duplicated implementations.
-- Fail early when template placeholders were not replaced.
-- Use OIDC where the registry path is configured and supported, with explicit token fallbacks elsewhere.
-- Require install/build/test/package checks before any publish step.
-- Keep the starter small, but not fake in the critical paths.
-
-## Phase 0: Stabilize the Template Baseline
-
-Purpose: make the current scaffold safe to evolve and hard to misuse.
-
-### P0
-
-- Add a release-readiness validator that fails on placeholder metadata.
-- Validate package names, crate name, binary names, repository URLs, author fields, and obvious placeholder strings.
-- Add a root documentation index under `docs/` so implementation docs have a stable home.
-
-### P1
-
-- Normalize naming conventions across Cargo, npm, and PyPI packages.
-- Define the canonical command name and the expected wrapper naming pattern.
-- Document the template customization surface:
-  project name, package ids, repo URL, author, license, binary name, description.
-
-### P2
-
-- Remove or tighten weak placeholder copy in README files.
-- Add a checklist for creating a new project from the template.
-
-### Exit Criteria
-
-- A new maintainer can identify every required rename/customization step.
-- CI can fail automatically if placeholder identity leaks into a release path.
-
-## Phase 1: Establish the Canonical Core and Wrapper Parity
-
-Purpose: stop treating each ecosystem as a separate product stub.
-
-### P0
-
-- Make the Rust binary the canonical executable implementation.
-- Define a small, stable placeholder command contract:
-  `--help`, `version`, `health`, and one example command returning structured JSON.
-- Convert the JavaScript package into a real wrapper around the packaged binary.
-- Convert the Python package into a real wrapper around the packaged binary.
-- Ensure wrappers preserve exit codes, stdout, and stderr from the core binary.
-
-### P1
-
-- Move `wrapper-js` source to TypeScript and publish built JavaScript artifacts.
-- Add binary resolution logic for supported platforms in both wrappers.
-- Add wrapper tests that assert parity against the core binary output contract.
-
-### P2
-
-- Add a small shared contract document covering commands, arguments, output, and error behavior.
-- Add support for environment-based binary overrides for local development and debugging.
-
-### Exit Criteria
-
-- Rust, JS, and Python packages all exercise the same underlying behavior.
-- Wrapper packages no longer maintain separate hand-written CLI logic.
-
-## Phase 2: Production-Grade Quality Gates
-
-Purpose: make the scaffold trustworthy before publish automation runs.
-
-### P0
-
-- Expand CI to enforce core quality gates in all three environments.
-- Add Rust checks:
-  `cargo fmt --check`, `cargo clippy -- -D warnings`, `cargo test`.
-- Add JS/TS checks:
-  install, typecheck, test, package dry-run.
-- Add Python checks:
-  environment setup, tests, wheel/sdist build, install-from-built-artifact smoke test.
-- Add a cross-package parity job that verifies wrappers match core contract behavior.
-
-### P1
-
-- Add artifact-level smoke tests for packaged npm and wheel outputs.
-- Add a matrix strategy where it materially improves confidence for supported platforms.
-- Make CI logs and job names intentionally clear for template adopters.
-
-### P2
-
-- Add optional local aggregate commands or scripts for running all checks consistently.
-- Add a contributor quickstart for running the same quality gates outside CI.
-
-### Exit Criteria
-
-- A release candidate must pass formatting, linting, unit tests, packaging, and parity checks.
-- Published artifacts are verified before publish jobs run.
-
-## Phase 3: Robust Publishing with OIDC First and Concrete Fallbacks
-
-Purpose: keep publishing reliable even when registry auth or registry behavior is imperfect.
-
-### P0
-
-- Keep publish workflows rerun-safe with published-version detection before attempting release.
-- Use OIDC or trusted publishing where supported and configured.
-- For the current `ossplate` baseline:
-  PyPI uses OIDC, Cargo uses OIDC with `CARGO_TOKEN` fallback, and npm uses `NPM_TOKEN`.
-- Add explicit secret-based fallbacks:
-  `NPM_TOKEN`, PyPI API token, and `CARGO_REGISTRY_TOKEN`.
-- Make auth mode selection visible in workflow logs.
-- Preserve non-destructive handling of already-published versions.
-
-### P1
-
-- Document exact registry setup steps for both preferred and fallback auth modes.
-- Add validation that publish jobs fail clearly when neither OIDC nor token auth is configured.
-- Tighten registry-specific behavior:
-  npm public access, PyPI trusted publishing expectations, crates.io version detection and retry behavior.
-
-### P2
-
-- Add optional manual dispatch inputs for dry-run or targeted registry publish flows if they simplify maintenance.
-- Add guidance for organizations that intentionally disable OIDC and standardize on tokens.
-
-### Exit Criteria
-
-- Publish workflows are understandable, rerunnable, and resilient.
-- Auth failures are explicit and actionable rather than implicit or flaky.
-
-## Phase 4: Layered Testing Guidance and Scaffolding
-
-Purpose: teach adopters how to scale verification without overcomplicating the starter.
-
-### P0
-
-- Add docs for the default testing pyramid:
-  smoke, unit, integration/parity, and release verification.
-- Define minimum required tests for any project generated from this template.
-- Document how wrapper parity tests fit into the scaffold.
-
-### P1
-
-- Add optional docs for live end-to-end browser testing with Playwright when a generated project includes a web UI.
-- Clarify that Playwright is not a default requirement for non-UI projects.
-- Add example CI placement for smoke vs slower e2e suites.
-
-### P2
-
-- Add template examples of failure triage:
-  unit regression, packaging regression, publish regression, wrapper parity regression.
-
-### Exit Criteria
-
-- The testing strategy is clear enough that teams do not improvise incompatible structures from scratch.
-- Optional e2e guidance exists without forcing UI assumptions onto every project.
-
-## Phase 5: Architecture Shell and Scaling Docs
+## Current State
 
-Purpose: leave room for serious product evolution without bloating the first scaffold cut.
+`ossplate` is no longer a placeholder scaffold. It now ships as a real multi-registry tool with:
 
-### P1
+- 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
 
-- Add architecture docs for a hexagonal baseline:
-  domain, application, adapters, and delivery surfaces.
-- Define where product logic belongs and where it should not live.
-- Document wrappers as adapters rather than alternate implementations.
+Published names are aligned as:
 
-### P2
+- crates.io: `ossplate`
+- npm: `ossplate`
+- PyPI: `ossplate`
+- CLI: `ossplate`
 
-- Add an example directory shell that future projects can expand into as complexity grows.
-- Link to the stronger internal reference material that informed this structure.
-- Add ADR guidance if the template grows beyond a small starter.
+## Completed
 
-### Exit Criteria
+### Foundation
 
-- The template can scale into a maintainable project layout without major restructuring.
-- The initial starter remains small and understandable.
+- 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.
 
-## Recommended Execution Order
+### Product Surface
 
-1. Phase 0
-2. Phase 1
-3. Phase 2
-4. Phase 3
-5. Phase 4
-6. Phase 5
+- 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`.
 
-Rationale:
+### Packaging And Artifact Reality
 
-- Phase 0 prevents accidental misuse while the template is still changing.
-- Phase 1 fixes the most important structural flaw: duplicated CLI stubs.
-- Phase 2 makes the scaffold trustworthy.
-- Phase 3 hardens release automation after the package surfaces are stable.
-- Phase 4 and Phase 5 improve scale and adoption quality without blocking the core scaffold.
+- 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.
 
-## Suggested Near-Term Milestones
+### Quality Gates
 
-### Milestone A
+- 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.
 
-Complete Phases 0 and 1.
+### Publishing
 
-Outcome:
-`ossplate` becomes a real scaffold with one canonical core and thin wrappers.
+- 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).
 
-### Milestone B
+## Remaining Priorities
 
-Complete Phase 2 and the P0 items in Phase 3.
+## P1
 
-Outcome:
-the scaffold becomes release-grade with meaningful quality gates and robust publish behavior.
+- 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.
 
-### Milestone C
+## P2
 
-Complete Phases 4 and 5.
+- 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.
 
-Outcome:
-the scaffold becomes easier to adopt, extend, and scale across future projects.
+## P3
 
-## Current State
+- 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.
 
-Completed:
+## Release Maintenance
 
-- release-readiness checks are wired into CI
-- JS and Python are thin wrappers over the Rust core
-- the Rust core now provides `version`, `validate`, `sync`, `create`, and `init`
-- `ossplate.toml` is the canonical identity source for owned metadata surfaces
-- installed npm and Python artifacts now carry the staged scaffold payload for `create` and `init`
-- artifact smoke tests prove installed distributions can run `version`, `create`, and `validate`
-- scaffold payload staging is now driven by an explicit curated manifest instead of a broad repo snapshot
-- Python packaging stages distribution assets through its build hook
-- CI now enforces Rust formatting and clippy alongside the existing test/package checks
+- 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.
 
-## Next Steps
+## Suggested Next Work
 
-- expand `sync` ownership carefully beyond the root README identity block and into selected workflow identity fields where safe
-- improve `validate` and `sync --check` output further if diff-style rendering becomes necessary
-- keep the root verification workflow aligned with CI as new checks are added
-- harden publish workflows with the OIDC-first fallback strategy from Phase 3
+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.

package/scaffold/ossplate.toml

@@ -1,6 +1,6 @@
 [project]
 name = "Ossplate"
-description = "A practical baseline for shipping one project across Cargo, npm, and PyPI without starting from scratch every time."
+description = "Build one project, ship it everywhere."
 repository = "https://github.com/stefdevscore/ossplate"
 license = "Unlicense"
 

package/scaffold/wrapper-js/README.md

@@ -1,7 +1,28 @@
-# JavaScript Wrapper For Ossplate
+# Ossplate
 
-This package is the JavaScript wrapper surface for Ossplate.
+![Ossplate armor](https://raw.githubusercontent.com/stefdevscore/ossplate/dev/assets/illustrations/armour05platemail.png)
 
-It delegates to the canonical Rust binary instead of implementing its own CLI behavior.
+`ossplate` helps you start and maintain a project that ships the same CLI through Rust, npm, and PyPI.
 
-Use `OSSPLATE_BINARY` during local development to point the wrapper at a specific binary.
+Use it to:
+
+- create a new scaffolded project
+- initialize an existing directory
+- validate project identity and metadata
+- keep owned files in sync
+
+Common commands:
+
+```bash
+ossplate version
+ossplate create <target>
+ossplate init --path <dir>
+ossplate validate
+ossplate sync --check
+```
+
+Learn more:
+
+- [Main documentation](../docs/README.md)
+- [Testing guide](../docs/testing.md)
+- [Architecture](../docs/architecture.md)

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

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

package/scaffold/wrapper-js/package.json

@@ -3,7 +3,7 @@
   "bin": {
     "ossplate": "bin/ossplate.js"
   },
-  "description": "A practical baseline for shipping one project across Cargo, npm, and PyPI without starting from scratch every time.",
+  "description": "Build one project, ship it everywhere.",
   "devDependencies": {
     "@types/node": "^24.6.0",
     "typescript": "^5.9.3"
@@ -39,5 +39,5 @@
     "test": "npm run build && node --test test/cli.test.js"
   },
   "type": "module",
-  "version": "0.1.0"
+  "version": "0.1.2"
 }

package/scaffold/wrapper-py/README.md

@@ -1,7 +1,28 @@
-# Python Wrapper For Ossplate
+# Ossplate
 
-This package is the Python wrapper surface for Ossplate.
+![Ossplate armor](https://raw.githubusercontent.com/stefdevscore/ossplate/dev/assets/illustrations/armour05platemail.png)
 
-It delegates to the canonical Rust binary instead of implementing its own CLI behavior.
+`ossplate` helps you start and maintain a project that ships the same CLI through Rust, npm, and PyPI.
 
-Use `OSSPLATE_BINARY` during local development to point the wrapper at a specific binary.
+Use it to:
+
+- create a new scaffolded project
+- initialize an existing directory
+- validate project identity and metadata
+- keep owned files in sync
+
+Common commands:
+
+```bash
+ossplate version
+ossplate create <target>
+ossplate init --path <dir>
+ossplate validate
+ossplate sync --check
+```
+
+Learn more:
+
+- [Main documentation](../docs/README.md)
+- [Testing guide](../docs/testing.md)
+- [Architecture](../docs/architecture.md)

package/scaffold/wrapper-py/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ossplate"
-version = "0.1.0"
-description = "A practical baseline for shipping one project across Cargo, npm, and PyPI without starting from scratch every time."
+version = "0.1.2"
+description = "Build one project, ship it everywhere."
 readme = "README.md"
 requires-python = ">=3.10"
 license = { text = "Unlicense" }

package/dist/index.d.ts

@@ -1,10 +0,0 @@
-export declare function resolveOssplateBinary(options?: {
-    baseDir?: string;
-    platform?: NodeJS.Platform;
-    arch?: string;
-}): string;
-export declare function runOssplate(args?: string[], options?: {
-    baseDir?: string;
-    platform?: NodeJS.Platform;
-    arch?: string;
-}): void;

package/dist/index.js

@@ -1,56 +0,0 @@
-import { accessSync, constants } from "node:fs";
-import { spawn } from "node:child_process";
-import { fileURLToPath } from "node:url";
-import { dirname, join } from "node:path";
-import { arch as runtimeArch, platform as runtimePlatform } from "node:os";
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const ENV_OVERRIDE = "OSSPLATE_BINARY";
-const TEMPLATE_ROOT_ENV = "OSSPLATE_TEMPLATE_ROOT";
-const TARGETS = {
-    darwin: { arm64: "darwin-arm64", x64: "darwin-x64" },
-    linux: { x64: "linux-x64" },
-    win32: { x64: "win32-x64" }
-};
-export function resolveOssplateBinary(options = {}) {
-    const envOverride = process.env[ENV_OVERRIDE];
-    if (envOverride) {
-        return envOverride;
-    }
-    const platform = options.platform ?? runtimePlatform();
-    const arch = options.arch ?? runtimeArch();
-    const target = TARGETS[platform]?.[arch];
-    if (!target) {
-        throw new Error(`Unsupported platform/arch: ${platform}/${arch}`);
-    }
-    const executable = platform === "win32" ? "ossplate.exe" : "ossplate";
-    const baseDir = options.baseDir ?? join(__dirname, "..");
-    const packagedPath = join(baseDir, "bin", target, executable);
-    assertExecutable(packagedPath);
-    return packagedPath;
-}
-export function runOssplate(args = [], options = {}) {
-    const binPath = resolveOssplateBinary(options);
-    const baseDir = options.baseDir ?? join(__dirname, "..");
-    const child = spawn(binPath, args, {
-        stdio: "inherit",
-        env: {
-            ...process.env,
-            [TEMPLATE_ROOT_ENV]: process.env[TEMPLATE_ROOT_ENV] ?? join(baseDir, "scaffold")
-        }
-    });
-    child.on("exit", (code) => {
-        process.exit(code ?? 0);
-    });
-    child.on("error", (error) => {
-        console.error(`ossplate: ${error.message}`);
-        process.exit(1);
-    });
-}
-function assertExecutable(filePath) {
-    try {
-        accessSync(filePath, constants.X_OK);
-    }
-    catch {
-        throw new Error(`Bundled ossplate binary not found or not executable at ${filePath}`);
-    }
-}