Ship NodeKit launch factory and freeze application contracts

AGENTS.md

@@ -0,0 +1,14 @@
+# NodeKit coding-agent entrypoint
+
+When a user supplies a business pain point, purpose, use case, hackathon brief, judging rubric, or sponsor tools, read `plugins/nodekit/skills/nodekit-launch/SKILL.md` and follow it as the launch workflow.
+
+The default outcome is not a plan. It is the smallest credible application that is researched, scaffolded, compiled, evaluated, live-provider tested, browser tested, deployable, and accompanied by sanitized proof and a phase-by-phase timeline.
+
+Safety boundaries:
+
+- Prefer official, current sponsor documentation and record sources and versions.
+- Never copy a secret into files, YAML, browser code, logs, or receipts. Pass it only to the process that needs it.
+- Ask before paid activation, production data migration, destructive writes, public posting, or production deployment unless the user already authorized that exact action.
+- Never weaken evaluators or substitute a different implementation in benchmark mode.
+- `nodekit create` is empty-directory only. Use `nodekit adopt` for an existing repository.
+- Keep the launch clock honest. Reused research or fixtures must be labeled as reused rather than timed as new work.

CLAUDE.md

@@ -0,0 +1,7 @@
+# NodeKit launch routing
+
+If the user describes an idea, business problem, use case, hackathon, or required sponsor stack, immediately load and follow:
+
+`plugins/nodekit/skills/nodekit-launch/SKILL.md`
+
+Treat the user's prose as the intake brief. Research only the high-impact unknowns, choose one demonstrable vertical slice, and use NodeKit to produce a working application and proof. Preserve the approval and secret-handling rules in `AGENTS.md`.

README.md

@@ -1,8 +1,44 @@
-# Node Platform
+# NodeKit / Node Platform
 
-Node Platform is the machine-readable ownership and repository-contract layer for the Node ecosystem. It prevents new contract forks while the existing applications continue to ship independently.
+NodeKit is the portable setup and conformance layer for proof-carrying agent applications. It turns an empty directory or an existing repository into a filesystem-authored agent harness with a compiled definition, capability packs, deterministic fixtures, live-provider gates, browser proof, and phase-by-phase receipts.
 
-P0 deliberately does not move working product code between repositories. It records who owns each concept, classifies current adapters and migration sources, standardizes lifecycle commands, and fails CI when a new canonical-signature copy or clear layer violation appears.
+Node Platform remains its ownership layer: it records which repository owns each shared contract and fails CI when a new fork or clear layer violation appears.
+
+## From a brief to a running app
+
+Clone this repository, open it in Codex or Claude Code, and describe the pain point, user, outcome, sponsor tools, and deadline. Root `AGENTS.md` and `CLAUDE.md` route that brief into the bundled NodeKit launch skill.
+
+Or use the CLI directly:
+
+```bash
+node src/cli.mjs create ../my-agent-app \
+  --name my-agent-app \
+  --brief "A persistent research agent that users can steer mid-run" \
+  --sponsors pi-ai,convex \
+  --package-manager pnpm \
+  --local-proof \
+  --nodekit-specifier file:$(pwd)
+
+cd ../my-agent-app
+npm run demo
+npm run eval
+npm run dev
+```
+
+The first certified preset is `research-loop`: a small reference runtime with an objective held-out metric, deterministic keep/revert decisions, versioned human intervention, interrupted-run recovery, a strict Pi smoke, and sanitized reproduction receipts. It is a reference adapter to the NodeAgent application contract; it is not presented as the still-unfinished extraction of NodeRoom's deeper production runtime.
+
+`npm run proof` works before credentials exist: it emits a passing `local-ready` receipt after the deterministic demo and evaluation. If live Pi, browser, or deployment receipts are present, every attempted gate must pass; the receipt becomes `release-ready` only when all three are present and green.
+
+Every created or adopted repository receives the same three coding-agent skills
+under both `.claude/skills/` and `.codex/skills/`:
+
+- `nodekit-launch` turns the brief into the smallest proof-carrying vertical slice;
+- `nodekit-qa` verifies the rendered journey, runtime, durable artifact, and receipt;
+- `nodekit-present` turns the same revision-bound evidence into an editable change,
+  judge, or release presentation through an available NodeSlide transport.
+
+Adoption never overwrites a user-owned skill with the same path; the collision is
+preserved in `proof/adoption-receipt.json` for explicit review.
 
 ## Commands
 
@@ -16,6 +52,15 @@ npm run ecosystem:check
 npm run dashboard
 ```
 
+Factory commands:
+
+```bash
+nodekit create <empty-directory> --name <slug> --brief <text>
+nodekit adopt <existing-directory> --name <slug> --brief <text>
+nodekit compile --repo-root <directory>
+nodekit inspect --repo-root <directory>
+```
+
 From any repository with `nodekit.yaml`:
 
 ```bash
@@ -25,21 +70,35 @@ npx --yes @homenshum/nodekit check
 npx --yes @homenshum/nodekit proof
 ```
 
-For a source-pinned fallback, replace `@homenshum/nodekit` with `github:HomenShum/node-platform#v0.1.0`. The unscoped `nodekit` npm name belongs to an unrelated project; this project uses the `@homenshum/nodekit` package and exposes the `nodekit` binary.
+`@homenshum/nodekit` 0.2.0 is not yet published. Until it is tagged and released, use a normalized local `file:` spec while dogfooding. The unscoped `nodekit` npm name belongs to an unrelated project.
 
-## P0 Contract
+## Contracts
 
 - [`ownership.yaml`](ownership.yaml) names one owner, current package, target package, status, version, and consumers for every governed concept.
 - [`repositories.yaml`](repositories.yaml) records lifecycle, support state, role, successor, and command profile.
 - [`architecture.yaml`](architecture.yaml) defines universal commands, allowed reuse modes, and source-layer rules.
-- [`schemas/nodekit.schema.json`](schemas/nodekit.schema.json) documents each consumer repository's `nodekit.yaml`.
+- [`schemas/nodekit.schema.json`](schemas/nodekit.schema.json) enforces `nodekit.repo/v1` for each consumer repository's `nodekit.yaml`.
+- [`schemas/nodeagent.application.v1.schema.json`](schemas/nodeagent.application.v1.schema.json) and [`schemas/nodeagent.pack.v1.schema.json`](schemas/nodeagent.pack.v1.schema.json) enforce the application and capability-pack contracts during compilation.
+- [`schemas/nodeagent.event.v1.schema.json`](schemas/nodeagent.event.v1.schema.json) defines the canonical portable event envelope. Applications resolve `nodeagent.event/v1` and `nodeagent.trace/v1` contract references even when an older v1 manifest omits the optional `contracts` block.
+- `nodekit compile` discovers authored files, validates pack references, rejects literal secrets, and hashes the runtime, backend, fixtures, schemas, integrations, and evals into `.nodeagent/`.
+- `nodekit create` refuses non-empty targets. `nodekit adopt` writes missing files only, preserves host scripts, and emits a collision receipt.
 - `nodekit repo check` validates ownership declarations, command aliases, migration origins, signature classification, and source rules.
 - `nodekit ecosystem check` checks all active local clones together.
 - `nodekit dashboard` generates the cross-repository status table.
 
-## Honest Boundary
+## Frozen v1 manifest dialect
+
+The three public v1 manifests use one flat, fail-closed shape:
+
+```yaml
+schemaVersion: nodekit.repo/v1 # or nodeagent.application/v1 / nodeagent.pack/v1
+```
+
+The earlier planning-only `apiVersion` / `kind` / `metadata` / `spec` envelope is not another accepted v1 dialect. Repository checks and application compilation reject that shape with a migration-oriented error. Existing `nodeagent.application/v1` manifests that predate the optional `contracts` block remain compatible; the compiler resolves their event and trace references to the canonical v1 values.
+
+## Honest boundary
 
-`planned`, `migration-planned`, and `canonical-unpackaged` are intentionally distinct from a released shared package. P0 freezes new duplication; it does not claim the P1 package extraction, environment loader, templates, codemods, or release automation are complete.
+`planned`, `migration-planned`, and `canonical-unpackaged` remain intentionally distinct from released shared packages. NodeKit now has one end-to-end reference preset; it does not claim that every runtime adapter, backend, template, codemod, or production deployment target is complete. In particular, NodeRoom still contains the deepest live runtime and its extraction into a published NodeAgent package remains separate work.
 
 See [`docs/DECISIONS.md`](docs/DECISIONS.md) for the ownership split and migration rules.
 The coordinated consumer commits, pull requests, hosted checks, and known limits are recorded in [`docs/P0_ROLLOUT.md`](docs/P0_ROLLOUT.md) and [`proof/p0-rollout.json`](proof/p0-rollout.json).

changes/nodekit-factory-p1/change.yaml

@@ -0,0 +1,77 @@
+schemaVersion: nodekit.change-story/v1
+id: nodekit-factory-p1
+title: Portable agent-app factory and injectable presentation system
+changeType: architecture
+audience:
+  - technical-reviewer
+  - hackathon-builder
+  - open-source-developer
+presentationTier: 3
+problem:
+  previousState: Agent applications, runtime adapters, proof formats, repository conventions, and presentation tooling were implemented independently across repositories.
+  painOrRisk: A coding agent had to rediscover setup, runtime, evaluation, deployment, and storytelling paths for every project; benchmark and production behavior could diverge.
+  affectedUsers:
+    - hackathon participants
+    - founders using Codex or Claude Code
+    - maintainers of Node ecosystem applications
+decision:
+  selectedApproach: Freeze flat NodeKit and NodeAgent contracts, generate or additively adopt the harness, keep runtimes replaceable through adapters, make proof portable, and extract NodeSlide into governed packages and transports.
+  alternatives:
+    - build another monolithic agent framework
+    - force every repository into one physical tree immediately
+    - keep NodeSlide as a standalone-only application
+  tradeoffs:
+    - more explicit contracts and migration ledgers
+    - stacked pull requests must land in dependency order
+    - production deployment and package publication remain separate approval gates
+implementation:
+  affectedSystems:
+    - NodeKit / node-platform
+    - NodeAgent
+    - NodeSlide
+    - NodeProof
+    - NodeTrace
+    - NodeMem
+    - NodeRoom
+    - NodeBenchAI
+    - NodeVideo
+    - NodeVoice
+    - NodeTasks
+    - BetterPRHandoff
+    - FeatureClipStudio
+  importantContracts:
+    - nodekit.repo/v1
+    - nodeagent.application/v1
+    - nodeagent.pack/v1
+    - nodeagent.event/v1
+    - nodeagent.trace/v1
+    - proofloop.receipt/v1
+    - nodetasks.corpus-receipt/v1
+    - betterprhandoff.handoff/v1
+    - featureclip.evidence-manifest/v1
+    - featureclip.evidence-receipt/v1
+    - NodeSlide repository and patch contracts
+proofRequirements:
+  - generated empty-directory local-ready application
+  - additive brownfield adoption with collision receipt
+  - NodeAgent Pi adapter package proof
+  - NodeSlide package and second-consumer proof
+  - NodeSlide CLI/MCP external-agent proof
+  - NodeTasks corpus integrity proof
+  - BetterPRHandoff to Change Story compilation proof
+  - FeatureClipStudio media-to-Evidence-Index projection proof
+  - canonical proof envelope validation
+  - cross-repository registry validation
+approvalBoundaries:
+  - merge to default branches
+  - npm publication
+  - production deployment
+  - paid resource activation
+  - destructive migration
+limitations:
+  - under-30 setup has a fast observed pass but is not repeatably certified
+  - NodeSlide core, controlled React surfaces, and the NodeRoom consumer proof are merged; the remaining implementation branches are reviews
+  - no package was published and no production deployment was performed
+  - NodeSlide editable canvas and PPTX export/reopen certification remain open
+  - NodeBench native-runtime parity and honest no-key profile remain open
+nextMilestone: Forward-test and review the dependency-ordered PR set, mount the NodeSlide React UI and production adapter in NodeRoom, then certify one live hackathon application without changing the benchmark execution path.

changes/nodekit-factory-p1/presentation/change-card.application.json

@@ -0,0 +1,104 @@
+{
+  "schemaVersion": "nodeslide.file-application/v1",
+  "snapshot": {
+    "deck": {
+      "schemaVersion": "nodeslide.slidelang/v1",
+      "toolchainVersion": "local-slidelang-adapter/1.1.0",
+      "id": "deck:nodekit-factory-p1",
+      "projectId": "project:nodekit",
+      "title": "NodeKit Factory P1",
+      "brief": {
+        "prompt": "Explain the NodeKit factory P1 rollout without upgrading draft evidence into release claims.",
+        "audience": "technical reviewers and hackathon builders",
+        "purpose": "Change review",
+        "successCriteria": [
+          "The system boundary is understandable.",
+          "Verified evidence and open release gates remain distinct."
+        ]
+      },
+      "theme": {
+        "id": "nodekit-review",
+        "name": "NodeKit review",
+        "mode": "light",
+        "colors": {
+          "canvas": "#f8f7f2",
+          "ink": "#17201b",
+          "muted": "#617068",
+          "accent": "#216e4e",
+          "accentSoft": "#dcefe5",
+          "insight": "#e9e3cf",
+          "insightInk": "#443d24",
+          "trace": "#132b24",
+          "border": "#c9cec9"
+        },
+        "typography": {
+          "display": "Aptos Display",
+          "body": "Aptos",
+          "data": "Aptos Mono"
+        },
+        "defaultRadius": 8,
+        "spacingUnit": 8
+      },
+      "slideOrder": ["deck:nodekit-factory-p1:slide:1"],
+      "version": 2,
+      "status": "ready",
+      "createdAt": 1784515200000,
+      "updatedAt": 1784515200001
+    },
+    "slides": [
+      {
+        "id": "deck:nodekit-factory-p1:slide:1",
+        "deckId": "deck:nodekit-factory-p1",
+        "title": "Problem, contract, proof",
+        "background": "#f8f7f2",
+        "elementOrder": ["deck:nodekit-factory-p1:slide:1:title"],
+        "version": 2
+      }
+    ],
+    "elements": [
+      {
+        "id": "deck:nodekit-factory-p1:slide:1:title",
+        "slideId": "deck:nodekit-factory-p1:slide:1",
+        "name": "Title",
+        "kind": "text",
+        "role": "title",
+        "bbox": { "x": 0.08, "y": 0.12, "width": 0.82, "height": 0.24 },
+        "rotation": 0,
+        "content": "P1 factory | Draft contracts, verified local seams",
+        "style": { "color": "#17201b", "fontSize": 38, "fontWeight": 700 },
+        "sourceIds": ["source:nodekit-factory-p1:evidence-index"],
+        "locked": false,
+        "exportCapabilities": ["web_native", "pptx_editable"],
+        "version": 2
+      }
+    ],
+    "sources": [
+      {
+        "id": "source:nodekit-factory-p1:evidence-index",
+        "deckId": "deck:nodekit-factory-p1",
+        "title": "NodeKit Factory P1 evidence index",
+        "sourceType": "document",
+        "retrievedAt": 1784515200000,
+        "citation": "../story/evidence-index.json",
+        "format": "json",
+        "provider": "nodekit-change-story",
+        "retention": "until_deleted",
+        "status": "ready"
+      }
+    ]
+  },
+  "receipt": {
+    "id": "application:039db09490de59dce3d36d60b922b101",
+    "proposalId": "proposal:6a06b6872de43772d0db038fda160e5a",
+    "deckId": "deck:nodekit-factory-p1",
+    "baseDeckVersion": 1,
+    "resultingDeckVersion": 2,
+    "baseSnapshotDigest": "sha256:464cd9d5021cf2c1dcf556822ae58828ab8b3f6f54ec0ca09d293fca31b74031",
+    "resultingSnapshotDigest": "sha256:b742c7321effa324e0a99f6942ef49596d6eaecfb21666d5d49db7ae7e36abaf",
+    "patchDigest": "sha256:c1be9d504068abd4360a4eb37d2fafed75c640bb0e4ba661a37163154343695c",
+    "approval": "exact_proposal_id",
+    "appliedAt": "2026-07-20T04:41:43.531Z",
+    "affectedSlideIds": ["deck:nodekit-factory-p1:slide:1"],
+    "affectedElementIds": ["deck:nodekit-factory-p1:slide:1:title"]
+  }
+}

changes/nodekit-factory-p1/presentation/change-card.patch.json

@@ -0,0 +1,28 @@
+{
+  "id": "patch:nodekit-factory-p1:review-copy",
+  "deckId": "deck:nodekit-factory-p1",
+  "baseDeckVersion": 1,
+  "baseSlideVersions": {
+    "deck:nodekit-factory-p1:slide:1": 1
+  },
+  "baseElementVersions": {
+    "deck:nodekit-factory-p1:slide:1:title": 1
+  },
+  "scope": {
+    "kind": "elements",
+    "deckId": "deck:nodekit-factory-p1",
+    "slideIds": ["deck:nodekit-factory-p1:slide:1"],
+    "elementIds": ["deck:nodekit-factory-p1:slide:1:title"],
+    "operationMode": "copy"
+  },
+  "operations": [
+    {
+      "op": "replace_text",
+      "slideId": "deck:nodekit-factory-p1:slide:1",
+      "elementId": "deck:nodekit-factory-p1:slide:1:title",
+      "text": "P1 factory | Draft contracts, verified local seams"
+    }
+  ],
+  "source": "agent",
+  "summary": "Tighten the change-card title so draft and verified states remain distinct."
+}

changes/nodekit-factory-p1/presentation/change-card.proposal.json

@@ -0,0 +1,47 @@
+{
+  "schemaVersion": "nodeslide.file-proposal/v1",
+  "id": "proposal:6a06b6872de43772d0db038fda160e5a",
+  "status": "ready",
+  "applied": false,
+  "createdAt": "2026-07-20T04:41:43.305Z",
+  "base": {
+    "deckId": "deck:nodekit-factory-p1",
+    "deckVersion": 1,
+    "snapshotDigest": "sha256:464cd9d5021cf2c1dcf556822ae58828ab8b3f6f54ec0ca09d293fca31b74031"
+  },
+  "patch": {
+    "id": "patch:nodekit-factory-p1:review-copy",
+    "deckId": "deck:nodekit-factory-p1",
+    "baseDeckVersion": 1,
+    "baseSlideVersions": {
+      "deck:nodekit-factory-p1:slide:1": 1
+    },
+    "baseElementVersions": {
+      "deck:nodekit-factory-p1:slide:1:title": 1
+    },
+    "scope": {
+      "kind": "elements",
+      "deckId": "deck:nodekit-factory-p1",
+      "slideIds": ["deck:nodekit-factory-p1:slide:1"],
+      "elementIds": ["deck:nodekit-factory-p1:slide:1:title"],
+      "operationMode": "copy"
+    },
+    "operations": [
+      {
+        "op": "replace_text",
+        "slideId": "deck:nodekit-factory-p1:slide:1",
+        "elementId": "deck:nodekit-factory-p1:slide:1:title",
+        "text": "P1 factory | Draft contracts, verified local seams"
+      }
+    ],
+    "source": "agent",
+    "summary": "Tighten the change-card title so draft and verified states remain distinct."
+  },
+  "candidate": {
+    "committedAt": 1784515200001,
+    "deckVersion": 2,
+    "snapshotDigest": "sha256:b742c7321effa324e0a99f6942ef49596d6eaecfb21666d5d49db7ae7e36abaf",
+    "affectedSlideIds": ["deck:nodekit-factory-p1:slide:1"],
+    "affectedElementIds": ["deck:nodekit-factory-p1:slide:1:title"]
+  }
+}