@receiz/ai-skills 103.0.0 → 105.0.0

package/README.md

@@ -1,14 +1,18 @@
 # Receiz AI Skills
 
+`receiz-app-builder-skill` is the authoritative v105 workflow for starting,
+integrating, upgrading, diagnosing, and repairing repositories through the typed
+Receiz app contract, shared SDK compiler, CLI, and MCP tools.
+
 This package teaches AI agents how to understand, verify, build with, and operate Receiz from the existing repository surfaces.
 
-It is published as `@receiz/ai-skills` and is an exact-version dependency of both `@receiz/sdk` and `@receiz/mcp-server`. Installing either package places these eight skill directories under `node_modules/@receiz/ai-skills` for explicit loading by an agent host.
+It is published as `@receiz/ai-skills` and is an exact-version dependency of both `@receiz/sdk` and `@receiz/mcp-server`. Installing either package places these nine skill directories under `node_modules/@receiz/ai-skills` for explicit loading by an agent host.
 
 Receiz is a proof-native artifact system. A Receiz object is not a database row. It is a proof-carrying artifact. The artifact's witnessed history is the truth boundary. Server state, database state, UI state, marketplace state, and model memory are projections only. Old witnessed truth is not stale. If a projection is wrong, rebuild it from object history. If truth is missing, append new truth. Never mutate witnessed truth.
 
 ## SDK, MCP, And Skills
 
-- SDK: `@receiz/sdk` is for building apps. It exposes validators, projections, proof memory, identity artifact helpers, public app-state, public store, commerce, wallet, sports, world, offline queues, webhooks, and sandbox helpers.
+- SDK: `@receiz/sdk` is the universal runtime; `@receiz/sdk/react` is React-only; `@receiz/sdk/compiler` is Node-only; `@receiz/sdk/testing` is browser-safe sandbox and conformance support.
 - MCP: `@receiz/mcp-server` is for agent tool access. It exposes SDK-backed tools for diagnostics, public reads, offline shape inspection, app-state/public-store actions, deterministic previews, and delegated writes. Artifact verification remains SDK `verification.verifyArtifact(file)` and requires continuity.
 - Skills: this package is operating doctrine. It tells an AI which Receiz primitive is active, which source of truth wins, which SDK or MCP rail to use, and what must never be assumed.
 

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@receiz/ai-skills",
-  "version": "103.0.0",
+  "version": "105.0.0",
   "description": "Authoritative Receiz AI operating skills for proof-native SDK and MCP agents.",
   "type": "module",
   "files": [
     "README.md",
+    "receiz-app-builder-skill",
     "receiz-builder-skill",
     "receiz-commerce-skill",
     "receiz-distribution-skill",
@@ -28,4 +29,4 @@
   "publishConfig": {
     "access": "public"
   }
-}
+}

package/receiz-app-builder-skill/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: receiz-app-builder-skill
+description: Use when starting, integrating, upgrading, diagnosing, or repairing a TypeScript or Next.js repository that uses Receiz application contracts, SDK compiler commands, generated files, or MCP app tools.
+---
+
+# receiz-app-builder-skill
+
+Build and upgrade Receiz applications from one typed contract. The compiler is
+integration tooling beneath Receiz proof truth; inspection is not verification.
+
+## When To Use This Skill
+
+- Use for `defineReceizApp`, `receiz.app.contract.v1`, or `receiz app` commands.
+- Use when adding Receiz to an existing repository or changing feature rails.
+- Use for deterministic integration plans, generated-file repair, and upgrades.
+- Use before calling Receiz MCP application compiler tools.
+
+## When Not To Use This Skill
+
+- Do not use repository inspection to verify an artifact.
+- Do not use it to invent proof objects, owners, continuity, or settlement.
+- Do not bypass `receiz-proof-skill` for byte-bearing artifact verification.
+
+## Core Receiz Laws
+
+- Never treat a database, server, marketplace, UI, model response, or cache as final authority.
+- The sealed proof object remains stronger than SDK, compiler, MCP, AI, and repository state.
+- Proof-object creation uses authenticated native Record before Seal.
+- Existing witnessed history is never rewritten; append missing truth and rebuild incorrect projections.
+- MCP inspection is not verification and MCP never becomes proof authority.
+
+## Required Behavior
+
+Select the package boundary first: universal runtime from `@receiz/sdk`, React bindings from `@receiz/sdk/react`, Node-only app compiler APIs from `@receiz/sdk/compiler`, and sandbox/conformance support from `@receiz/sdk/testing`.
+
+1. Inspect the explicit repository root with `receiz_project_inspect` or `receiz app inspect`.
+2. Identify intended features and create or update the contract with `defineReceizApp` or `receiz_app_contract_create`.
+3. Compile a read-only plan with `compileReceizAppContract`, `receiz_app_plan`, or `receiz app plan`.
+4. Explain scopes, authority boundaries, findings, and every proposed file.
+5. Obtain explicit confirmation for the exact preview digest before mutation.
+6. Apply the smallest safe change set with `receiz_app_apply` or `receiz app apply`.
+7. Run generated conformance, `receiz conformance`, and repository tests.
+8. Reinspect with `receiz_app_check` and report exact evidence.
+9. Use `receiz_app_upgrade` for version-aware upgrades and `receiz_app_explain` for findings.
+10. Report remaining manual work and blocked authority without claiming completion.
+
+Read [resources/workflow.md](resources/workflow.md) for new, existing, feature-change,
+upgrade, diagnosis, and repair routes.
+
+## Forbidden Behavior
+
+- Never invent APIs, tools, scopes, proof IDs, owners, settlement, verification results, authorization, or completed file changes.
+- Never write outside the explicit repository root or follow a symlink outside it.
+- Never overwrite unmarked application code.
+- Never put tokens, keys, identity artifacts, webhook secrets, or recovery material in code, plans, fixtures, logs, or MCP output.
+- Never add a traditional database as proof authority.
+- Never claim a plan, inspection, hash, MCP lookup, or successful compile verified a proof object.
+
+## MCP Usage Rules
+
+Use the documented tools listed in
+[resources/workflow.md](resources/workflow.md). Inspection, contract proposals,
+planning, checking, upgrade planning, and explanation are read-only.
+`receiz_app_apply` returns a preview first and requires the exact digest as
+explicit confirmation. Every response must retain the MCP authority boundary.
+Use `receiz_app_repair` for confirmed deterministic repair, `receiz_scope_explain` for canonical scopes, `receiz_release_qualify` for read-only release evidence, `receiz_proof_trace` only with canonical artifact bytes for a verdict, and `receiz_webhook_replay` only after signature verification and exact confirmation.
+
+## SDK Usage Rules
+
+Import `defineReceizApp`, `validateReceizAppContract`,
+`compileReceizAppContract`, `inspectReceizProject`,
+`planReceizIntegration`, `checkReceizIntegration`, `planReceizUpgrade`, and
+`explainReceizIntegrationFinding` from `@receiz/sdk/compiler`. Artifact verification remains
+`verification.verifyArtifact`; creation remains the SDK's authenticated native
+Record-before-Seal rail.
+
+## Output Format
+
+```md
+Contract:
+Repository evidence:
+Features and scopes:
+Authority boundary:
+Read-only findings:
+Proposed files:
+Preview digest:
+Confirmation status:
+Checks run:
+Remaining manual work:
+What is proven:
+What is not proven:
+```
+
+## Safety And Security Boundaries
+
+Read [resources/authority-boundaries.md](resources/authority-boundaries.md).
+Stop when a required delegated permission, identity proof, capability, or user
+decision is unavailable. Report the blocked boundary; do not fabricate it.
+Generated browser code may contain public origins but never server credentials.
+`receiz.extensions.ts` is developer-owned and create-once; regeneration must never overwrite it. Emulator evidence is `sandboxVerified`, never a production verified verdict.
+
+## Examples
+
+- [Commerce](examples/commerce.md)
+- [Marketplace](examples/marketplace.md)
+- [Persistent world](examples/persistent-world.md)
+- [AI-operated application](examples/ai-operated.md)
+- [Profile or portfolio](examples/profile-portfolio.md)
+- [Content publishing](examples/content-publishing.md)
+- [Proof verifier](examples/proof-verifier.md)
+- [Minimal proof object](examples/minimal-proof-object.md)
+
+Resources:
+
+- [Workflow](resources/workflow.md)
+- [Authority boundaries](resources/authority-boundaries.md)
+- [Generated-file repair](resources/generated-file-repair.md)
+- [Upgrade rules](resources/upgrade-rules.md)

package/receiz-app-builder-skill/examples/ai-operated.md

@@ -0,0 +1,5 @@
+# AI-Operated Application Starter Contract
+
+Select only the feature rails the agent needs. Keep planning and inspection
+read-only, require explicit confirmation for mutations, and use delegated scopes
+as permission rather than proof authority.

package/receiz-app-builder-skill/examples/commerce.md

@@ -0,0 +1,6 @@
+# Commerce Starter Contract
+
+Use `defineReceizApp` with features `identity`, `proof`, `proofMemory`,
+`publicStore`, `commerce`, `media`, and `webhooks`. Compile the plan before
+adding checkout or publication. Ownership and settlement remain distinct proof
+boundaries.

package/receiz-app-builder-skill/examples/content-publishing.md

@@ -0,0 +1,5 @@
+# Content And Publishing Starter Contract
+
+Select `identity`, `proof`, `proofMemory`, `publicStore`, `media`, and
+`webhooks`. Publication is an authenticated append and does not replace the
+sealed source proof.

package/receiz-app-builder-skill/examples/marketplace.md

@@ -0,0 +1,5 @@
+# Marketplace Starter Contract
+
+Select `identity`, `proof`, `proofMemory`, `publicStore`, `commerce`, `media`,
+and `webhooks`. Require continuity-bound verification before listing projections
+and settlement authority before value transfer.

package/receiz-app-builder-skill/examples/minimal-proof-object.md

@@ -0,0 +1,5 @@
+# Minimal Proof-Object Starter Contract
+
+Select `identity` and `proof`. Use a real authenticated Receiz ID and the native
+Record-before-Seal sequence. Do not expose a path that seals before continuity
+exists.

package/receiz-app-builder-skill/examples/persistent-world.md

@@ -0,0 +1,5 @@
+# Persistent World Starter Contract
+
+Select `identity`, `proof`, `proofMemory`, `media`, `webhooks`, and `world`.
+First-paint durable verified world truth and append verified additions without
+replacing witnessed state.

package/receiz-app-builder-skill/examples/profile-portfolio.md

@@ -0,0 +1,4 @@
+# Profile Or Portfolio Starter Contract
+
+Select `identity`, `proof`, `proofMemory`, `publicStore`, and `media`. Preserve
+owner Receiz ID continuity and project public originals only after verification.

package/receiz-app-builder-skill/examples/proof-verifier.md

@@ -0,0 +1,5 @@
+# Proof Verifier Starter Contract
+
+Select `proof` and optionally `proofMemory`. Route byte-bearing files to SDK
+`verification.verifyArtifact`. MCP inspection and repository checks never supply
+the verification verdict.

package/receiz-app-builder-skill/resources/authority-boundaries.md

@@ -0,0 +1,15 @@
+# Authority Boundaries
+
+- Inspection reports repository evidence. It proves no artifact bytes.
+- Verification validates the sealed proof object's integrity, owner, namespace,
+  and continuity through the SDK verifier.
+- Publication appends an authenticated projection; it does not create ownership
+  or settlement by implication.
+- Settlement requires the implemented settlement primitive and appropriate
+  delegated or identity-proof authority.
+- Proof creation requires a real authenticated Receiz ID and native Record
+  before Seal continuity.
+
+When authority is unavailable, return
+`blocked_missing_capability_or_authority`. Never synthesize a Receiz ID, owner,
+namespace, prior head, scope, token, proof ID, verification, or settlement.

package/receiz-app-builder-skill/resources/generated-file-repair.md

@@ -0,0 +1,10 @@
+# Generated-File Repair
+
+Receiz-owned generated files carry `@receiz-generated` or the
+`receiz.generated-files.v1` manifest. Preview regeneration, compare the digest,
+and request confirmation before writing.
+
+Automatic edits are limited to generated files, approved `package.json` fields,
+and explicit generated blocks. Unmarked source becomes a manual action. Preserve
+all unrelated code. Reject traversal, symlink escape, stale previews, and content
+whose digest changed after review.

package/receiz-app-builder-skill/resources/upgrade-rules.md

@@ -0,0 +1,11 @@
+# Upgrade Rules
+
+Compare the repository, contract, installed SDK/MCP/AI-skills versions, and
+target SDK version. Keep findings deterministic and version-aware.
+
+- Preserve valid historical proof objects.
+- Never rewrite witnessed history.
+- Append missing truth.
+- Rebuild incorrect projections from stronger verified truth.
+- Align package versions and reject published `workspace:` dependency ranges.
+- Re-run tarball installation and conformance after upgrades.

package/receiz-app-builder-skill/resources/workflow.md

@@ -0,0 +1,17 @@
+# App Contract Workflow
+
+| Need | Read-only action | Confirmed mutation |
+|---|---|---|
+| New app | `receiz_app_contract_create`, `receiz_app_plan` | `receiz_app_apply` |
+| Existing repository | `receiz_project_inspect`, `receiz_app_plan` | Apply the confirmed preview |
+| Add or remove a rail | Update the contract, then plan | Apply only the changed digest |
+| Upgrade | `receiz_app_upgrade` | Apply approved package/generated changes |
+| Diagnose | `receiz_app_check`, `receiz_app_explain` | None until the finding is understood |
+| Repair | `receiz_app_repair` preview | Exact digest confirmation; regenerate Receiz-owned files only |
+
+After every mutation, run the returned verification commands and reinspect.
+The same repository must produce zero changes on the second run.
+Preserve the developer-owned `receiz.extensions.ts` sibling on every run. Finish with `receiz conformance` or `receiz_release_qualify`.
+
+Do not substitute inspection for verification, publication for settlement, or a
+successful write for proof admission.

package/receiz-builder-skill/SKILL.md

@@ -12,6 +12,7 @@ Build Receiz apps from proof objects, durable public projections, proof memory,
 - Use for no-db storefronts, product pages, marketplaces, pack opening apps, profile vaults, proof pages, claim flows, QR entry flows, custom domains, subdomains, and template apps.
 - Use when generating app code that imports `@receiz/sdk` or `@receiz/sdk/react`.
 - Use when an AI must choose SDK rails for public store, app state, checkout, media, identity, wallet, sports, or offline queues.
+- For contract-driven repository integration or upgrades, use `receiz-app-builder-skill` first and use this skill for the resulting application surfaces.
 
 ## When Not To Use This Skill
 

package/receiz-mcp-agent-skill/resources/mcp-tool-map.md

@@ -1,11 +1,31 @@
 # MCP Tool Map
 
+## v105 Application Compiler And Semantic Operations
+
+| Need | Tool | Mutation |
+|---|---|---|
+| Inspect repository | `receiz_project_inspect` | Read-only |
+| Propose contract | `receiz_app_contract_create` | Read-only |
+| Compile plan | `receiz_app_plan` | Read-only |
+| Preview/apply | `receiz_app_apply` | Exact digest confirmation required |
+| Check conformance | `receiz_app_check` | Read-only |
+| Plan upgrade | `receiz_app_upgrade` | Read-only |
+| Explain finding | `receiz_app_explain` | Read-only |
+| Repair application | `receiz_app_repair` | Exact digest confirmation required |
+| Trace proof | `receiz_proof_trace` | Read-only; canonical bytes required for verified verdict |
+| Replay webhook | `receiz_webhook_replay` | Signature verification and exact confirmation required |
+| Explain scope | `receiz_scope_explain` | Read-only |
+| Qualify release | `receiz_release_qualify` | Read-only |
+
+Repository inspection is not verification. These tools never supply an artifact
+verification verdict or proof authority.
+
 Source: `packages/receiz-mcp-server/src/index.ts`.
 
 ## Diagnostics And Setup
 
 - `receiz_doctor`: SDK doctor for app/tenant diagnostics.
-- `receiz_capabilities`: inspect SDK capability readiness.
+- `receiz_capabilities`: use `capabilities.describe` for deterministic support and probe mode for readiness.
 - `receiz_required_scopes`: return stable scope constants by rail.
 - `receiz_runtime_blueprint`: return app runtime blueprint.
 - `receiz_authorize_url`: build Connect/OIDC authorize URL.
@@ -32,6 +52,7 @@ Source: `packages/receiz-mcp-server/src/index.ts`.
 - `receiz_proof_query`: delegated proof query projection.
 
 Use SDK `verification.verifyArtifact(file)` for verification; it requires enclosing integrity and ownership continuity.
+Emulator output is labeled `sandboxVerified`; never translate it into Receiz verification.
 
 ## Sports, Wallet, World
 

package/receiz-proof-skill/resources/sdk-reference.md

@@ -1,5 +1,12 @@
 # SDK Reference For Proof Work
 
+The v105 app compiler APIs (`defineReceizApp`, `compileReceizAppContract`, and
+repository planning/checking functions) inspect and integrate applications.
+They do not verify proof bytes. Continue to use `verification.verifyArtifact`
+for the indivisible integrity, owner, namespace, and continuity verdict.
+
+Import runtime proof APIs from `@receiz/sdk`, React bindings from `@receiz/sdk/react`, compiler APIs from `@receiz/sdk/compiler`, and sandbox/conformance helpers from `@receiz/sdk/testing`. Emulator evidence is `sandboxVerified`, not production verification.
+
 Source: `packages/receiz-sdk/src/index.ts`, `packages/receiz-sdk/src/identity.ts`, `packages/receiz-sdk/src/react.ts`, and SDK package docs.
 
 ## Core Constants And Schemas

package/receiz-skill-bundle/resources/skill-routing.md

@@ -2,13 +2,14 @@
 
 ## Route Order
 
-1. If an object must be verified, start with `receiz-proof-skill`.
-2. If local files or airplane-mode proof are involved, use `receiz-offline-verifier-skill`.
-3. If MCP tools or delegated access are involved, use `receiz-mcp-agent-skill`.
-4. If code or app surfaces are being generated, use `receiz-builder-skill`.
-5. If product, storefront, order, receipt, certificate, note, or checkout boundaries appear, use `receiz-commerce-skill`.
-6. If sports cards, card memory, Pack Derby, rarity, MLB proof language, or live events appear, use `receiz-sports-card-skill`.
-7. If QR, venue, affiliate, staff script, or physical activation appears, use `receiz-distribution-skill`.
+1. If a repository is being started, integrated, upgraded, diagnosed, or repaired, use `receiz-app-builder-skill`.
+2. If an object must be verified, start with `receiz-proof-skill`.
+3. If local files or airplane-mode proof are involved, use `receiz-offline-verifier-skill`.
+4. If MCP tools or delegated access are involved, use `receiz-mcp-agent-skill`.
+5. If code or app surfaces are being generated, use `receiz-builder-skill`.
+6. If product, storefront, order, receipt, certificate, note, or checkout boundaries appear, use `receiz-commerce-skill`.
+7. If sports cards, card memory, Pack Derby, rarity, MLB proof language, or live events appear, use `receiz-sports-card-skill`.
+8. If QR, venue, affiliate, staff script, or physical activation appears, use `receiz-distribution-skill`.
 
 ## Multi-Skill Order