NodeKit

In one sentence: NodeKit generates applications and then proves what they did.

40 seconds to a running, proof-carrying app (measured from a cold clone)

git clone https://github.com/HomenShum/NodeKit
cd NodeKit && npm install
node src/cli.mjs create ../my-app --name my-app --brief "triage inbound support tickets"
cd ../my-app && npm install && npm run demo

That command sequence produced this: the created app's npm run dev page, recorded headless with Playwright (scripts/record-readme-first-win.mjs) after its npm run demo reported "passed": true. The guided case walks confirm → propose → approve → Completion verified, ending on the canonical artifact and its content-addressed receipt. Deterministic demo runtime, no API keys.

That is a working agent application with a compiled definition, deterministic fixtures, and a no-key demo — 40 seconds end to end when this section was written, "passed": true from the demo's own output, and it is the same creation path exercised by the factory acceptance gate. When it works, run npm run proof inside your app to see the receipt trail. Coding-agent users skip all of this:

/plugin marketplace add HomenShum/NodeKit
/plugin install nodekit

then describe your pain point — the nodekit-launch skill routes it. (Or clone the repo and open it; AGENTS.md/CLAUDE.md route the same way.)

Everything below is the reference for what the platform is and how it proves itself. You do not need it to build your first app. Unfamiliar terms are in GLOSSARY.md; a ten-minute orientation is in START_HERE.md.

Going to change the code rather than use it?

Read these instead, in this order. They exist so a new engineer can run, trace and change this repository without the person who built it sitting beside them — the HUMAN-READY gate is the standard they answer to.

Read	For
docs/START_HERE.md	Trace create, then the generated app, optional tools, and separately invoked tests
.tours/	The same three walkthroughs inside VS Code, pointing at live source (CodeTour)
docs/codebase/STRUCTURE.md	Find implementation, templates, contracts, and historical records
docs/codebase/ARCHITECTURE.md	The one invariant everything else is downstream of
docs/codebase/CONCERNS.md	Historical findings and reproduction commands; recheck them on your revision
docs/SIMPLIFICATION_REPORT.md	Before/after measurements for the last reduction pass, with every evidence command

Also: docs/codebase/STACK.md, CONVENTIONS.md, INTEGRATIONS.md, TESTING.md.

Looking for another project? Choose a repository by the developer task.

NodeKit is the figured-out product foundation and conformance layer for proof-carrying agent applications. It turns an empty directory or existing repository into a domain-blank application with one guided lifecycle, a compiled definition, deterministic fixtures, browser proof, and receipts.

Blank in domain. Figured out in behavior. Convex-first, not Convex-locked.

Release gating, certification status, and the attestation trust model live in docs/GOVERNANCE.md — maintainer territory; you do not need it to build your first app.

The disposable workspace-reference-index stores bounded Caseflow artifact refs and digests only. Native workspace, session, and checkpoint artifacts remain canonical; the index cannot resume or authorize a session.

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.

Before expanding the build, use the 90-second field card in the idea-to-reality principles to freeze one user job, one primary artifact, the complexity budget, authority boundaries, proof, and the observation that will drive the next iteration.

Or use the CLI directly. Install dependencies first — every command below needs them:

npm install

Record any agent command and open the generated static report:

node src/cli.mjs agent run --agent codex --goal "Inspect the repository" -- node --version

By default, NodeKit writes stable workspace identity to .nodekit/agent-runs/workspace.json, stable per-agent session identity under .nodekit/agent-runs/sessions/, and each invocation to .nodekit/agent-runs/<run-id>/{receipt.json,report.html}. Use --out <dir> to move the entire store. The newest 50 completed runs are retained.

The recorder runs and captures one local child process: exact command arguments, exit state, bounded stdout/stderr, and lifecycle events. Exact I/O may contain sensitive data, so treat both artifacts as sensitive and review them before sharing. Each stream retains at most 256 KiB while preserving observed byte counts and full-stream digests. NodeKit itself performs no network request or deployment for agent run; the child command may do either. The recorder does not independently observe detached descendants, child-created files, tool calls, network activity, or inherited environment values.

node src/cli.mjs create ../my-agent-app \
  --name my-agent-app \
  --brief "Carry one user intention to a reviewed and verified artifact" \
  --package-manager pnpm \
  --local-proof

cd ../my-agent-app
pnpm demo
pnpm eval
pnpm dev

The primary creation path has no preset and no silent domain default. It generates the stable product grammar:

Case -> Run -> Stage -> Artifact -> Proposal -> Approval -> Receipt

The generated app includes docs/FIGURED_OUT.md, a product brief, audience placeholder, user journey, service blueprint, experience contract, design direction, taste contract, a responsive artifact-first UI, and a deterministic in-memory conformance demo.

There is no domain chooser, public preset catalog, or silent fallback. Narrow examples in this source repository are regression fixtures and historical demonstrations only: they are not shipped in the npm package and cannot be selected by the creation CLI. The coding agent starts from the same blank foundation every time, researches the user's actual workflow, and adds only the domain behavior that job requires.

pnpm proof works before credentials exist in the pnpm quickstart: it emits a passing local-ready receipt after the deterministic demo and evaluation. Supplied browser evidence must pass. The generated proof script may label a passing result browser-certified when certified browser evidence is present, but it always reports releaseReady: false and lists remaining release gates. These generated-application levels are not NodeKit Ease certification or Convex submission authorization. Use the equivalent script command for the package manager selected at creation.

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

From this repository:

npm install
npm run doctor
npm test
npm run ecosystem:check
npm run dashboard

Continue native-agent sessions safely

@homenshum/nodekit/native-agent-identity provides the owner/workspace-scoped continuity contract for desktop restarts, scheduled runs, and inbox handoffs. Caseflow stores exactly three canonical artifacts: workspace, agent session, and checkpoint. Provider session identity is hashed; raw IDs stay inside the trusted adapter.

The public surface is workspace_bind, session_start, session_checkpoint, session_resume, and session_status. RESUMED is returned only after exact repository remeasurement, a trusted receipt, an operational lease, and a new durable checkpoint. The execution graph remains a disposable projection and cannot authorize continuity.

See the native-agent identity contract.

Compare copied behavior

Design tokens can preserve appearance while silently changing interaction timing. NodeKit's first behavior-portability check compares static CSS motion declarations across repositories, binds the exact source set, and emits reviewable migration aliases:

node src/cli.mjs motion compare \
  /path/to/source-repository \
  /path/to/destination-repository \
  --output proof/motion-portability.json

The command returns PASS, FAIL, or NOT_RUN; missing coverage is never green. Its receipt is decisive for static name/value conflicts only and explicitly leaves runtime, DOM/trace, video, and audience evidence unrun. See docs/BEHAVIOR_PORTABILITY_SHOWCASE.md for the measured NodeSlide/NodeRoom example.

By default, nodekit create vendors the exact compile/check runtime that generated the project under vendor/nodekit and records file:vendor/nodekit in package.json. This keeps a fresh clone installable and prevents a later GitHub branch change from silently changing compile or proof semantics. Pass --nodekit-specifier <exact-specifier> only when an externally versioned package or immutable Git commit should replace the vendored runtime. The bundle is deliberately runtime-only; use the source repository or a future published package to scaffold additional projects.

The domain-blank base has an executable empty-directory gate:

npm run acceptance:factory

It creates a clean temporary base application, installs dependencies, compiles it, runs tests, the deterministic guided journey, stale-proposal evaluation, the structural live HTTP/DOM contract, and a real Playwright journey. Phase-level timers and candidate-bound screenshot sidecars are written under proof/ease/latest/; the fail-closed summary remains proof/factory-acceptance.json. A passing core browser journey is not Ease certification while required states, fresh-agent trials, human usability, deployment, and real consumers remain open.

After freezing a clean candidate, the local engineering gate is one explicit preflight followed by one exact proof command:

npm run candidate:check
npm run candidate:prove -- --candidate <40-character-commit> --source-hash <64-character-sha256>

candidate:prove records repository and component tests, both public type checks, the component build, production dependency audit, registry/ecosystem checks, Evolution Ledger verification, exact package/archive installation, and the generated app's structural live HTTP browser contract. It writes ten candidate-bound check receipts, a zero-P0/P1 issue inventory, and proof/engineering-health-verdict.json. This is a local engineering verdict only. It does not run the rendered screenshot matrix, hosted timing or agent/human studies, deploy, publish, authorize a Convex submission, or claim external certification.

The consolidated strategy, evidence-backed status, Harness Gym roadmap, and ordered checklist are in docs/NODEKIT_MASTER_PLAN.md. The complete submission lock, cross-platform workflow, fresh-agent protocol, and uncoached human-study thresholds are documented in docs/EASE_PROOF.md. The cross-platform workflow is manual so a reviewer can deliberately label a run cold or warm; one matrix run is evidence, not a percentile claim. The five-person study now has a privacy-safe append-only operator (npm run ease:human-study -- help) and exact runbook in docs/FRESH_HUMAN_USABILITY_STUDY.md. That collector does not create participants or close the still-external 0/5 human gate.

The adopted evidence-driven model profiling, executable skill, and capability-routing architecture is in docs/MODEL_INTELLIGENCE.md. Its implemented P0 commands do not make provider calls or certify routing from an empty evidence set.

Factory commands (a --local-proof run creates an initial local Git commit so receipts have an immutable candidate to bind to):

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>
nodekit graph import --repo-root <directory> --commit <sha>
nodekit graph init --repo-root <directory>
nodekit graph query <terms> --repo-root <directory>
nodekit graph gaps --repo-root <directory>
nodekit graph harness-sync --repo-root <directory>
nodekit harness init --repo-root <directory>
nodekit models baseline --repo-root <directory>
nodekit models profile --repo-root <directory>
nodekit models inspect --repo-root <directory>
nodekit models diagnose --repo-root <directory>

Runtime consumers use @homenshum/nodekit/knowledge-runtime for accepted-canonical traversal, Caseflow-bound context packs, durable retrieval receipts, and safe abstention. PostgreSQL-backed applications use @homenshum/nodekit/adapters/postgres/knowledge with the exported knowledge-migration.sql. See docs/KNOWLEDGE_EVOLUTION.md for the authority boundary and protected comparison contract.

From a generated or adopted repository carrying the vendored runtime:

pnpm doctor
pnpm demo
pnpm check
pnpm proof

Use the package manager selected at creation time; the commands above match the pnpm quickstart.

@homenshum/nodekit 0.2.1 is not yet published. Generated projects remain portable because they carry the exact runtime under vendor/nodekit. External consumers that do not use nodekit create should use an immutable Git or packed-tarball reference until the package is released. The unscoped nodekit npm name belongs to an unrelated project.

The packed package also exposes exact-consumer preparation, resumable managed-evidence capture, external evidence finalization, and Builder Gym directly:

nodekit-consumer-prepare --help
nodekit-evidence-capture --help
nodekit-evidence-finalize --help
nodekit harness builder status --repo-root <directory> --json

import { NODETRACE_VERDICT_DIMENSIONS, builderGymStatus } from "@homenshum/nodekit/builder-gym";
import { prepareExactConsumerPackage } from "@homenshum/nodekit/consumer-package-preparation";
import { startManagedEvidenceCampaign } from "@homenshum/nodekit/managed-evidence-capture";
import {
  recordReferenceObservation,
  scoreReferenceCandidate,
  verifyReferenceScoreReceipt,
} from "@homenshum/nodekit/reference-loop";
import { finalizeSubmissionEvidence } from "@homenshum/nodekit/submission-evidence-finalizer";

Consumer preparation is read-only unless --apply is supplied. Managed capture binds exact candidate identity, provider resources, elapsed phases, browser evidence, and cleanup receipts, but never creates or deletes those resources. Evidence finalization only signs already-measured evidence with a purpose-scoped external key. None of these commands deploys, publishes, submits, or certifies adoption. Follow the managed capture runbook for the external operator steps.

The provider-neutral reference contract and its fail-closed Mobbin boundary are documented in docs/REFERENCE_LOOP.md.

PostgreSQL adapter

NodeKit ships a driver-neutral, owner-scoped PostgreSQL Caseflow adapter. Apply the exported @homenshum/nodekit/adapters/postgres/migration.sql once, then provide a pool compatible with pg.Pool:

import { Pool } from "pg";
import { createPostgresCaseflow } from "@homenshum/nodekit/adapters/postgres";

const pool = new Pool({ connectionString: process.env.DATABASE_URL });
const caseflow = createPostgresCaseflow({
  pool,
  ownerId: authenticatedPrincipal.id,
});

The adapter uses transactions, row locks, advisory sequence locks, owner-scoped queries, idempotent active-run/decision/completion retries, and conditional artifact-version application. Run the shared suite against a disposable database with:

NODEKIT_POSTGRES_URL=postgresql://... npm run conformance:postgres -- --candidate-tarball=proof/ease/latest/nodekit-candidate.tgz --output=proof/postgres-conformance.json

The Supabase mapping ships as a core SQL export at @homenshum/nodekit/adapters/supabase/profile.sql plus an opt-in worker module at @homenshum/nodekit/adapters/supabase/workers.sql. The core profile adds authenticated-only owner reads, a principal-derived proposal RPC, explicit Realtime publication, and owner-folder Storage policies. The worker module enables a server-only PGMQ queue and pg_cron without exposing either to browser roles. Checked-in SQL is not a claim that live Supabase Auth, Storage, Realtime, Queue, or Cron conformance has passed; see adapters/supabase/README.md.

Repository directory

Start with the job you need to finish. These are the repositories listed in repositories.yaml; the descriptions summarize their maintained GitHub descriptions and entry pages observed on 2026-10-07. Open the repository's own README for setup and read its agent instructions before editing. This directory is a navigation aid, not a claim that every project is tested, published, licensed for reuse, or ready for production.

Developer task	Repository
Generate an agent application and use shared contracts	NodeKit
Integrate an agent with room context, documents, spreadsheets, and notes	NodeAgent
Build shared editing flows for humans and agents	NodeRoom
Work on reviewable AI edits to presentation decks	NodeSlide
Inspect the default NodeSlide app or the separately enabled local Parity UI workflow	parity-studio
Work on inspectable video reconstruction	NodeVideo
Coordinate agents in shared voice rooms	NodeVoice
Connect an app surface to its agent trace	NodeTrace
Add passive memory from agent activity streams	NodeMem
Use a proof supervisor for coding-agent work	NodeProof
Follow persona journeys and artifact-based UI QA	agentic-ui-qa
Find task corpora, benchmark adapters, and rubrics	NodeTasks

For a local checkout, rg --files finds the entry documents and rg "<symbol or topic>" finds the code that owns a change. Start with source directories; open recorded evidence when investigating the specific run it describes. Registry lifecycle labels and README claims do not replace checks bound to the revision you intend to use.

Contracts

• ownership.yaml names one owner, current package, target package, status, version, and consumers for every governed concept.
• repositories.yaml records lifecycle, support state, role, successor, and command profile.
• architecture.yaml defines universal commands, allowed reuse modes, and source-layer rules.
• schemas/nodekit.schema.json enforces nodekit.repo/v1 for each consumer repository's nodekit.yaml.
• schemas/nodeagent.application.v1.schema.json and schemas/nodeagent.pack.v1.schema.json enforce the application and capability-pack contracts during compilation.
• 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 emits a full application identity in .nodeagent/. The identity binds the agent, packs, integrations, backend, UI/app surface, scripts, workflow definitions, evaluations, fixtures, dependency locks, and recognized deployment configuration.
• nodekit graph import imports a pinned Understand Anything knowledge-graph.json as a namespaced, commit-bound code graph snapshot. nodekit graph query --code retrieves from that snapshot; it never turns the code graph into a write authority.

Frozen v1 manifest dialect

The three public v1 manifests use one flat, fail-closed shape:

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, implemented, previously proven, current-candidate proven, and published are intentionally different claims. NodeKit has a domain-blank base, portable memory semantics, an implemented PostgreSQL adapter with an earlier-revision PostgreSQL 17.10 live receipt, and a locally tested installable Convex Caseflow component. It also has the Supabase local profile and proof mechanics for exact browser export/reopen and recursive evidence verification.

None of those facts proves the mutable working tree is the final candidate. Three real authenticated Convex consumers, final-candidate timing and agent matrices, five real humans, live Supabase, an isolated deployed preview, real Knowledge Evolution adoption, and independent final verification remain separate evidence gates. See docs/REMAINING_GAPS.md.

See 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 and proof/p0-rollout.json. The overnight Casca/Agentic-RL delivery and morning adversarial-review sequence is in docs/NODEKIT_ULTRA_V1_HANDOFF.md.