owlrunkit 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.14.0
+
+- Adds ordinary `--help` and `--version`, read-only `doctor`, exact official
+  registry `adopt`, and deterministic `profiles detect`, `validate`, and
+  `impact` commands for self-service project onboarding.
+- Makes `init` guide new users through doctor, profile detection, then exact
+  adoption or Formal start while retaining a complete JSON machine view.
+- Includes the previously prepared Core v0.13 documentation corrections for
+  Quick verification, deterministic repair, offline transport,
+  registry-first adoption, and the canonical Codex Skill update boundary.
+- Updates the bundled Codex Skill and config template to Core `0.14.0`.
+- Keeps Contract v0.2 and OwlCoda CLI `0.15.31` unchanged.
+- Does not add signing, keys, GitHub Actions, or authority.
+
 ## 0.13.0
 
 - First standalone npm release of OwlRunKit.

package/README.md

@@ -11,16 +11,33 @@ release authority.
 ## Install
 
 ```bash
-npm install --save-exact owlrunkit@0.13.0
+npm install --save-exact owlrunkit@0.14.0
 ```
 
-Initialize and inspect a project:
+Check the ordinary CLI surface, then initialize a project:
 
 ```bash
+owlrunkit --help
+owlrunkit --version
 owlrunkit init --workspace /absolute/path/to/project
-owlrunkit inspect --workspace /absolute/path/to/project --json
+owlrunkit doctor --workspace /absolute/path/to/project
+owlrunkit profiles detect --workspace /absolute/path/to/project --dry-run
+owlrunkit adopt --workspace /absolute/path/to/project --exact owlrunkit@0.14.0
 ```
 
+`doctor` is read-only and distinguishes offline/DNS timeout, registry
+authentication, missing version, and local install binding failures. Profile
+detection is deterministic and dry-run only; use `profiles validate` and
+`profiles impact --changed` for supported profile checks. `adopt` writes typed
+evidence only after the exact installed package and lockfile match the official
+npm registry release.
+
+Use Quick Verification for one low-risk source-bound command that needs a
+reusable receipt but no writer lease or Formal acceptance. Use Formal Delivery
+for multi-writer, long-running, migration, integration, release, production,
+funds, or formally accepted work. A Quick receipt cannot become Formal
+acceptance, and accepted never grants Git or release authority.
+
 The package also includes the read-only verifier:
 
 ```bash
@@ -37,7 +54,8 @@ Those remain explicit external decisions even when verification passes.
 
 - Node.js 20.19 or newer
 - a local project directory
-- no network access for normal verification and recovery operations
+- network access only for explicit `doctor` registry diagnostics and `adopt`;
+  normal verification and recovery remain local
 
 ## License
 

package/docs/architecture/OWLCODA_RUN_KIT_CONTRACT_V0_2.md

@@ -453,6 +453,85 @@ claim that every provider exposes reliable remaining quota, reset time, or
 pricing. Live provider adapters require a separately verifiable source and may
 legitimately report typed unknown fields.
 
+## Core v0.13 standalone distribution, Quick verification and repair
+
+Core `0.13.0` is distributed through the standalone `owlrunkit` package. The
+RunKit package has an independent semantic version lifecycle from the
+`owlcoda` CLI; a RunKit packaging or documentation patch does not change the
+Contract `0.2` / Core `0.13.0` identity unless Core behavior or its bound
+dependency closure changes.
+
+Core `0.13.0` adds a bounded Quick Verification lane for one exact command
+without a writer lease or Formal acceptance. `quick-verify` records the
+pre/post workspace fingerprints, exact executable and argv, stdout/stderr
+materials, exit result and an authorization-free
+`OwlCodaQuickVerificationReceiptV1`. `quick-attest` recomputes the selected
+workspace and receipt bindings. `quick-metrics --local` reads only the
+project-owned receipt store and performs no telemetry or network access. A
+Quick `GO` remains `captured_verification`; it cannot satisfy the Formal
+Contract v0.2 acceptance gate.
+
+Deterministic `repair` persists a reviewable plan before replay, reuses only
+fresh receipt-bound coverage, replays pending exact argv, and appends
+replacement lineage. Failed and orphaned attempts remain inspectable. Repair
+cannot rewrite the parent receipt, lower risk, replace the executable after
+planning, or activate a green leaf after source/profile drift.
+
+`offline-export` and `offline-import` move exact receipt bytes through
+`OwlCodaOfflineAttestationBundleV1`. Export refuses an existing destination.
+Import is idempotent only when the stored receipt bytes match exactly and fails
+closed on conflicts, symlinked paths or malformed bundles. The embedded
+read-only attestation component is part of the standalone package; it does not
+need a separate public package for the first adoption wave.
+
+Formal cross-project adoption is registry-first. The installed package and
+controller-owned `OwlCodaRunKitRegistryReleaseEvidenceV1` must bind the same
+exact official npm registry version, 40-hex `shasum`, canonical SHA-512
+`integrity`, and exact tarball URL. A local directory, `file:` dependency,
+local tarball, symlink, workspace link, Git reference or mutable dist-tag can
+exercise a release candidate but is not formal adoption evidence.
+
+The canonical Codex Skill is assembled atomically with a content manifest that
+binds its Skill text, Core, contracts and attestation files. Known valid
+installations may be archived and replaced; unknown drift fails closed. Core
+`0.13.0` does not grant Git, npm, release, or foreign-project authority.
+Signing, keys, external anchors and GitHub Actions remain deferred.
+
+## Core v0.14 self-service onboarding
+
+Core `0.14.0` keeps Contract `0.2`, Quick/Formal lane separation, exact
+registry binding, append-only execution lineage, independent review and all
+authority boundaries unchanged. Its product change is the first-adoption
+surface of the standalone `owlrunkit` package:
+
+- top-level `--help` and `--version` follow ordinary CLI expectations and exit
+  successfully without creating project state;
+- `doctor` performs read-only Node, Core, config, package, registry, profile
+  and project-script diagnostics with a short network timeout and a typed
+  offline/DNS-timeout, authorization, missing-version and binding-mismatch
+  taxonomy;
+- `profiles detect --dry-run`, `profiles validate`, and
+  `profiles impact --changed` provide deterministic official entrypoints
+  without treating guessed profiles as authoritative configuration;
+- `adopt --exact owlrunkit@0.14.0` accepts only the official npm registry exact
+  version whose registry metadata and local install/lock binding pass the
+  existing strict adoption evaluator; and
+- `init` and `inspect` add a separate onboarding projection for
+  `doctor -> profiles detect --dry-run -> adopt or Formal start`.
+
+Read-only onboarding commands must not write project state or expose registry
+credentials. Adoption evidence is written atomically only after eligibility.
+Local directories, worktrees, `file:` or Git dependencies, local tarballs,
+workspace links and mutable tags remain fail-closed. Profile detection never
+overwrites existing config, and an implementation may omit `profiles apply`
+rather than infer authority from a deterministic suggestion.
+
+The onboarding projection is not the recovery state machine: a project with a
+stale Packet, invalid evidence or engine drift must still follow the Core's
+`nextAllowedAction`. Core `0.14.0` does not grant Git, npm, release, deploy or
+foreign-project authority. Signing, keys, external anchors and GitHub Actions
+remain deferred.
+
 ## Deferred work
 
 Contract v0.2 still does not add a built-in browser or Electron driver, Plugin,

package/integrations/codex/skills/owlcoda-runkit/SKILL.md

@@ -7,6 +7,9 @@ description: Run receipt-backed, project-owned software execution with OwlCoda R
 
 Use the bundled deterministic Core to coordinate work through project artifacts rather than chat memory. Require Node.js 20 or later.
 
+Current release: standalone `owlrunkit@0.14.0`, bundling Contract `0.2` and
+Core `0.14.0`. The root `owlcoda` package has a separate version lifecycle.
+
 The session is an execution interface. Project artifacts are the system of record.
 
 ## Start safely
@@ -22,8 +25,8 @@ Set `SKILL_ROOT` to this skill directory before running the examples below.
 ## Initialize and inspect
 
 ```bash
-node "$SKILL_ROOT/scripts/runkit-contract/runkit-cli.mjs" init --workspace "$PROJECT_ROOT"
-node "$SKILL_ROOT/scripts/runkit-contract/runkit-cli.mjs" inspect --json --workspace "$PROJECT_ROOT"
+owlrunkit init --workspace "$PROJECT_ROOT"
+owlrunkit inspect --json --workspace "$PROJECT_ROOT"
 ```
 
 Initialization may write only `.owlcoda/runkit/`. It must not modify business source.
@@ -53,6 +56,102 @@ dangling or non-regular control truth fails closed instead of appearing absent.
 Project config authority fields are validated before output, human text escapes
 control characters, and indexed ordering is locale independent.
 
+## Core v0.13 distribution, verification and recovery
+
+Core `0.13.0` introduced the standalone distribution, Quick verification and
+repair surfaces. OwlRunKit uses its own version lifecycle: the standalone
+`owlrunkit` npm package may change without changing the `owlcoda` CLI version.
+
+For one low-risk exact command, use the Core v0.13 Quick path:
+
+```bash
+node "$SKILL_ROOT/scripts/runkit-contract/runkit-cli.mjs" quick-verify \
+  --workspace "$PROJECT_ROOT" -- "$ABSOLUTE_EXECUTABLE" "arg-one"
+
+node "$SKILL_ROOT/scripts/runkit-contract/runkit-cli.mjs" quick-attest \
+  --workspace "$PROJECT_ROOT" --receipt "$QUICK_RECEIPT"
+
+node "$SKILL_ROOT/scripts/runkit-contract/runkit-cli.mjs" quick-metrics \
+  --workspace "$PROJECT_ROOT" --local
+```
+
+Quick receipts are `captured_verification`, not Formal acceptance. Metrics are
+local-only and perform no telemetry or network request.
+
+Core v0.13 also adds deterministic repair and exact-byte offline transport:
+
+```bash
+node "$SKILL_ROOT/scripts/runkit-contract/runkit-cli.mjs" repair \
+  --workspace "$PROJECT_ROOT" --run-id "$RUN_ID"
+
+node "$SKILL_ROOT/scripts/runkit-contract/runkit-cli.mjs" offline-export \
+  --workspace "$PROJECT_ROOT" --receipt "$RECEIPT" --output "$BUNDLE"
+
+node "$SKILL_ROOT/scripts/runkit-contract/runkit-cli.mjs" offline-import \
+  --workspace "$PROJECT_ROOT" --bundle "$BUNDLE" --store "$OFFLINE_STORE"
+```
+
+Repair must preserve the failed attempt and append replacement lineage. Offline
+export refuses an existing target; import is idempotent only for identical
+bytes. Neither operation grants authority.
+
+Formal cross-project adoption is registry-first adoption. It requires an exact
+published `owlrunkit` version plus matching official npm registry `shasum`,
+`integrity`, tarball URL, and controller-owned release evidence. A local
+worktree, directory, `file:` dependency, local tarball, symlink, workspace link,
+Git ref, or mutable dist-tag may test a release candidate but is not evidence
+for formal adoption.
+
+Do not hand-edit an installed Skill. Inspect or atomically refresh it from an
+authoritative package/repository with:
+
+```bash
+node "$RUNKIT_PACKAGE_ROOT/scripts/runkit-contract/install-codex-skill.mjs" \
+  inspect --target "$RUNKIT_SKILL_TARGET"
+
+node "$RUNKIT_PACKAGE_ROOT/scripts/runkit-contract/install-codex-skill.mjs" \
+  install --repository "$RUNKIT_PACKAGE_ROOT" \
+  --target "$RUNKIT_SKILL_TARGET" --archive "$RUNKIT_SKILL_ARCHIVE_ROOT"
+```
+
+The install manifest binds every Skill, Core, contract and attest file.
+Unknown installed drift fails closed instead of being overwritten. An accepted
+receipt, ready-for-commit receipt, package publication, or valid install still
+does not grant Git, npm, release, deploy, or foreign-project authority.
+
+## Core v0.14 self-service onboarding
+
+The bundled Core is `0.14.0`. New users should not need internal module calls,
+an external schema validator, or the full Formal lifecycle merely to understand
+whether a project can adopt RunKit.
+
+```bash
+owlrunkit --help
+owlrunkit --version
+owlrunkit doctor --workspace "$PROJECT_ROOT"
+owlrunkit profiles detect --workspace "$PROJECT_ROOT" --dry-run
+owlrunkit profiles validate --workspace "$PROJECT_ROOT"
+owlrunkit profiles impact --workspace "$PROJECT_ROOT" --changed path/to/file
+owlrunkit adopt --workspace "$PROJECT_ROOT" --exact owlrunkit@0.14.0
+```
+
+`doctor` and `profiles detect --dry-run` are read-only. Registry diagnostics use
+a short timeout and distinguish offline or DNS/timeout failures, authorization
+failures, missing versions and local-install binding mismatches without
+printing credentials. Profile detection is deterministic evidence for a human
+decision; it does not write or overwrite project configuration.
+
+`adopt` accepts only an exact `owlrunkit@0.14.0` binding from the official npm
+registry. It recomputes the registry and local install/lock facts, invokes the
+strict adoption evaluator, and writes typed project evidence only after an
+eligible result. Worktrees, `file:` dependencies, local tarballs, Git sources,
+workspace links and mutable tags remain ineligible.
+
+`init` and `inspect` expose an onboarding projection that points new users to
+`doctor`, dry-run profile detection, and then exact adoption or Formal start.
+This projection does not replace the Core recovery action and does not grant
+authority.
+
 ## Choose the smallest assurance lane
 
 Choose the lane before planning. Do not create a Formal execution merely

package/integrations/codex/skills/owlcoda-runkit/assets/templates/config.json

@@ -2,7 +2,7 @@
   "schemaVersion": "OwlCodaRunKitConfigV2",
   "core": {
     "contractVersion": "0.2",
-    "coreVersion": "0.12.0",
+    "coreVersion": "0.14.0",
     "coreManifestSha256": "sha256:replace-with-installed-core-manifest",
     "coreSourceRef": "artifact:sha256:replace-with-content-addressed-source"
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "owlrunkit",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Project-owned execution, evidence, verification, and recovery for coding agents.",
   "license": "GPL-3.0-or-later",
   "author": "yeemio <owlclaw@163.com>",

package/packages/attest/distribution-manifest-v1.json

@@ -36,6 +36,11 @@
     "sha256": "sha256:3972dc9744f6499f0f9b2dbf76696f2ae7ad8af9b23dde66d6af86c9dfb36986"
   },
   "supportedProducerCoreIdentities": [
+    {
+      "contractVersion": "0.2",
+      "coreVersion": "0.14.0",
+      "coreManifestSha256": "sha256:d3b498562bebb2fa180d6861cb834ce3551288bf499ce0d769ee6c64b2663231"
+    },
     {
       "contractVersion": "0.2",
       "coreVersion": "0.13.0",

package/packages/attest/src/quick.mjs

@@ -18,6 +18,11 @@ import { captureWorkspaceSnapshot } from "./workspace-snapshot.mjs";
 export { validQuickReceiptShape } from "./quick-receipt-contract.mjs";
 
 export const SUPPORTED_QUICK_CORE_IDENTITIES = Object.freeze([
+  {
+    contractVersion: "0.2",
+    coreVersion: "0.14.0",
+    coreManifestSha256: "sha256:d3b498562bebb2fa180d6861cb834ce3551288bf499ce0d769ee6c64b2663231",
+  },
   {
     contractVersion: "0.2",
     coreVersion: "0.12.0",

package/registry-release-policy-v1.json

@@ -2,7 +2,7 @@
   "schemaVersion": "OwlCodaRunKitRegistryReleasePolicyV1",
   "status": "release_candidate_unpublished",
   "packageName": "owlrunkit",
-  "candidateVersion": "0.13.0",
+  "candidateVersion": "0.14.0",
   "registry": "https://registry.npmjs.org",
   "registryRequiredBeforeAdoption": true,
   "exactVersionRequired": true,

package/sbom.spdx.json

@@ -2,8 +2,8 @@
   "spdxVersion": "SPDX-2.3",
   "dataLicense": "CC0-1.0",
   "SPDXID": "SPDXRef-DOCUMENT",
-  "name": "owlrunkit-0.13.0",
-  "documentNamespace": "https://owlcoda.com/spdx/owlrunkit/0.13.0",
+  "name": "owlrunkit-0.14.0",
+  "documentNamespace": "https://owlcoda.com/spdx/owlrunkit/0.14.0",
   "creationInfo": {
     "created": "2026-07-29T00:00:00Z",
     "creators": [
@@ -14,8 +14,8 @@
     {
       "name": "owlrunkit",
       "SPDXID": "SPDXRef-Package-OwlRunKit",
-      "versionInfo": "0.13.0",
-      "downloadLocation": "https://registry.npmjs.org/owlrunkit/-/owlrunkit-0.13.0.tgz",
+      "versionInfo": "0.14.0",
+      "downloadLocation": "https://registry.npmjs.org/owlrunkit/-/owlrunkit-0.14.0.tgz",
       "filesAnalyzed": false,
       "licenseConcluded": "GPL-3.0-or-later",
       "licenseDeclared": "GPL-3.0-or-later",
@@ -24,7 +24,7 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/owlrunkit@0.13.0"
+          "referenceLocator": "pkg:npm/owlrunkit@0.14.0"
         }
       ]
     }

package/scripts/runkit-contract/core-contract.mjs

@@ -12,7 +12,7 @@ import { isAbsolute, relative, resolve, win32 } from "node:path";
 import { fileURLToPath } from "node:url";
 
 export const CONTRACT_VERSION = "0.2";
-export const CORE_VERSION = "0.13.0";
+export const CORE_VERSION = "0.14.0";
 export const RUNTIME_ROOT = ".owlcoda/runkit";
 
 const CORE_FILES = [
@@ -26,7 +26,9 @@ const CORE_FILES = [
   "lease-lifecycle.mjs",
   "lifecycle-orchestration.mjs",
   "offline-store.mjs",
+  "onboarding-doctor.mjs",
   "profile-impact.mjs",
+  "profile-onboarding.mjs",
   "provenance-common.mjs",
   "quick-attest.mjs",
   "quick-canonical.mjs",
@@ -36,6 +38,8 @@ const CORE_FILES = [
   "quick-workspace-snapshot.mjs",
   "ready-for-commit.mjs",
   "receipt-lineage.mjs",
+  "registry-adoption-gate.mjs",
+  "registry-adoption.mjs",
   "repair-execution.mjs",
   "resume-execution.mjs",
   "resource-preflight.mjs",
@@ -47,6 +51,7 @@ const CORE_FILES = [
   "verification-plan.mjs",
   "visual-smoke.mjs",
   "schemas/closeout-receipt-v2.schema.json",
+  "schemas/adoption-evidence-v1.schema.json",
   "schemas/coverage-adopt-request-v1.schema.json",
   "schemas/core-artifact.schema.json",
   "schemas/core-artifact-v2.schema.json",