From 3b2ab25376746816c9e5ba8b3643f0a97d99a4fa Mon Sep 17 00:00:00 2001 From: Antony Zaki Date: Sun, 26 Jul 2026 18:51:29 -0400 Subject: [PATCH 1/8] feat: add employer skill attribution product --- README.md | 15 + docs/README.md | 20 + docs/dependency-security-audit.md | 86 + ...t-onboarding-retention-and-monetization.md | 666 ++++++ site/.env.example | 22 + site/.gitignore | 3 + site/README.md | 80 +- site/app/api/invoke/[skillId]/route.ts | 33 +- site/app/components/InvokeControls.tsx | 164 ++ .../components/landing/AttributionSandbox.tsx | 384 ++++ site/app/components/landing/Hero.tsx | 115 + site/app/components/landing/PilotCta.tsx | 26 + site/app/components/landing/ProofLoop.tsx | 39 + .../components/landing/sandbox-model.test.mjs | 88 + site/app/components/landing/sandbox-model.ts | 218 ++ site/app/globals.css | 30 +- site/app/landing-content.ts | 65 + site/app/landing.module.css | 1940 +++++++++++++++++ site/app/layout.tsx | 12 +- site/app/manifesto.tsx | 149 +- site/app/page.tsx | 154 +- site/app/proof/page.tsx | 21 + site/next.config.ts | 20 + site/package-lock.json | 556 ++--- site/package.json | 25 +- 25 files changed, 4410 insertions(+), 521 deletions(-) create mode 100644 docs/README.md create mode 100644 docs/dependency-security-audit.md create mode 100644 docs/product-onboarding-retention-and-monetization.md create mode 100644 site/.env.example create mode 100644 site/app/components/InvokeControls.tsx create mode 100644 site/app/components/landing/AttributionSandbox.tsx create mode 100644 site/app/components/landing/Hero.tsx create mode 100644 site/app/components/landing/PilotCta.tsx create mode 100644 site/app/components/landing/ProofLoop.tsx create mode 100644 site/app/components/landing/sandbox-model.test.mjs create mode 100644 site/app/components/landing/sandbox-model.ts create mode 100644 site/app/landing-content.ts create mode 100644 site/app/landing.module.css create mode 100644 site/app/proof/page.tsx diff --git a/README.md b/README.md index b401027..5c3710d 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,19 @@ product. Every claim below is labeled measured, modeled, or hypothesis. [neverhandedover.com](https://neverhandedover.com)** (also at [skillassetprotocol.com](https://skillassetprotocol.com); source in [`site/`](site/)). +## Run the website locally + +Use Node 22, then run from the repository root: + +```bash +cd site +npm ci +npm run dev +``` + +Open . No environment file, wallet, or API key is needed +for the employer-facing product sandbox. + ## The demo result On 2026-07-12, one wallet paid per model call **and** per hosted-skill invocation over x402 @@ -45,6 +58,8 @@ All four proofs run with no API keys, no network payments, and no wallet. Where - **`CONTEXT.md`** — the ubiquitous language: Skill, Creator, Wielder, Beneficiary, Collar, Invocation, Derivative, Royalty claim. +- **`docs/product-onboarding-retention-and-monetization.md`** — a repo-grounded product review, + proposed employer-funded business model, validation gates, and prioritized roadmap. - **`docs/adr/`** — 8 decision records, including 0007 (the closed-mode compensation layer is the terminal product) and 0008 (the Wielder is a wallet, not a harness). - **`spikes/`** — pi-wielder (one wallet, two asset classes, unified ledger) and diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..be915ee --- /dev/null +++ b/docs/README.md @@ -0,0 +1,20 @@ +# Documentation + +## Product review + +- [Onboarding, retention, and monetization recommendations](product-onboarding-retention-and-monetization.md) + +## Security + +- [Dependency security audit](dependency-security-audit.md) + +## Architecture decisions + +- [ADR-0001 — Hosted invocation-rights](adr/0001-skills-as-hosted-invocation-rights.md) +- [ADR-0002 — Story programmable IP](adr/0002-tokenize-skills-as-programmable-ip-on-story.md) +- [ADR-0003 — Payment-gated execution](adr/0003-payment-gated-execution.md) +- [ADR-0004 — Economic and network moats](adr/0004-compete-on-moats-not-secrecy.md) +- [ADR-0005 — Two-leg settlement](adr/0005-two-leg-cross-chain-settlement.md) +- [ADR-0006 — Closed modes first](adr/0006-phased-rollout-closed-modes-first.md) +- [ADR-0007 — Closed-mode compensation as the terminal product](adr/0007-closed-mode-compensation-layer-as-terminal-product.md) +- [ADR-0008 — The Wielder is a wallet](adr/0008-the-wielder-is-a-wallet.md) diff --git a/docs/dependency-security-audit.md b/docs/dependency-security-audit.md new file mode 100644 index 0000000..fe4466b --- /dev/null +++ b/docs/dependency-security-audit.md @@ -0,0 +1,86 @@ +# Dependency security audit + +Date: 2026-07-26 + +Scope: the Next.js application in `site/`, including production and development +dependencies, the image optimizer path, and deployment-adjacent server code. + +## Executive summary + +- The original install reported 12 high-severity findings. +- `npm audit --omit=dev` now reports **0 vulnerabilities**. +- The full development tree reports 9 high-severity package entries. They all + trace to one `brace-expansion` denial-of-service advisory in the ESLint tool + chain, not nine independent defects. +- `npm audit fix --force` was rejected because npm proposes incompatible major + changes and invalid historical downgrades of the Next.js lint configuration. + +The remaining advisory is not reachable from the deployed application. It is +used by local lint glob matching over trusted repository configuration. Keep it +visible in CI and update when the ESLint/Next dependency chain publishes a +compatible release. + +## Remediation applied + +| Dependency | Before | After | Reason | +|---|---:|---:|---| +| `next` | 15.5.20 | 15.5.22 | Clears the direct Next.js advisories while staying on the existing release line. | +| `eslint-config-next` | 15.5.20 | 15.5.22 | Keeps framework and lint configuration aligned. | +| `postcss` | vulnerable transitive | 8.5.23 override | Pulls the patched same-major parser into the production tree. | +| `sharp` | 0.34.5 transitive | 0.35.3 override | Pulls the patched image processor; requires Node 20.9 or newer. | +| `brace-expansion` | 5.0.7 where compatible | 5.0.8 | Clears patched modern dependency paths. | + +The project pins Node `22.x` so local and Vercel builds use the same supported +major and satisfy Sharp's runtime requirement. + +The PostCSS and Sharp overrides are temporary compatibility controls. Remove +them when the selected Next.js release declares patched versions directly. +Sharp 0.35 is outside Next 15.5.22's declared `^0.34.3` range, so it received an +explicit build, runtime, and image-optimization smoke test before release. + +## Residual development advisory + +Advisory: +[GHSA-mh99-v99m-4gvg](https://github.com/advisories/GHSA-mh99-v99m-4gvg), +unbounded brace expansion causing an out-of-memory denial of service. + +Observed path: legacy `brace-expansion` 1.x through `minimatch` 3.x in ESLint, +`@eslint/eslintrc`, and plugins bundled by `eslint-config-next`. There is no +patched 1.x release. npm's forced proposals either downgrade core lint packages +to unrelated historical versions or cross unsupported major boundaries. + +Risk acceptance: + +- Development-only; absent from `npm audit --omit=dev`. +- Input is repository-owned lint configuration and file patterns, not an + untrusted network request. +- Linting should still run in a bounded CI job. +- Recheck on every dependency update and at least monthly while active. + +## Server safeguards added during review + +- The paid `/proof` invocation endpoint is disabled unless + `ENABLE_PAID_PROOF=true` is set explicitly. +- Request bodies are capped at 16 KiB and prompt input at 4,000 characters. +- Facilitator and model calls have abort deadlines; the route has an explicit + 60-second maximum duration. +- `PAY_TO_ADDRESS` must be a nonzero 20-byte EVM address. +- Global responses disable the framework signature and add CSP frame/base/object + restrictions, clickjacking protection, MIME sniffing protection, a strict + referrer policy, and a restrictive permissions policy. + +Do not enable paid proof on a public deployment until persistent rate limits and +an Anthropic account-level spend cap are configured. Free testnet USDC can still +trigger real model cost. + +## Verification record + +- `npm test`: 6/6 passing. +- `npm run lint`: passing. +- Clean `npm run build`: passing in an isolated copy to avoid the active local + development server rewriting `.next` concurrently. +- Production start smoke test: passing. +- Next image optimizer request for `/icon.png` at 64 px: HTTP 200, `image/png`. +- `npm audit --omit=dev`: 0 vulnerabilities. +- Full `npm audit`: 9 high package entries, all from the single dev-only advisory + described above. diff --git a/docs/product-onboarding-retention-and-monetization.md b/docs/product-onboarding-retention-and-monetization.md new file mode 100644 index 0000000..58bce72 --- /dev/null +++ b/docs/product-onboarding-retention-and-monetization.md @@ -0,0 +1,666 @@ +# Product onboarding, retention, and monetization recommendations + +**Status:** Proposal +**Reviewed:** 2026-07-25 +**Scope:** Repository, public site, offline proofs, accepted ADRs, and current market +benchmarks + +## Executive recommendation + +Make the closed-mode product a **B2B attribution and compensation control plane for +employee-authored AI Skills**: + +> Measure which reusable AI Skills create value inside an organization, preserve who +> created and maintains them, and turn trusted evidence into fair, configurable rewards. + +The employer is the buyer. The employee-Creator is the emotional center. The Wielder +should keep using the tools they already use. + +Monetize the control plane with an annual employer-paid program license, paid +implementation, and enterprise add-ons. Pass internal creator rewards through at 100%. +Keep x402, Story provenance, and external revenue sharing as optional infrastructure, +not as the first product or the primary source of revenue. + +The immediate goal should be **three paid design-partner pilots**, not more protocol +surface area. + +### The five decisions to make now + +1. **Fund internal compensation with an employer-controlled periodic reward pool.** + Invocation and outcome data should influence awards, but raw call count should not be + the payout formula. +2. **Lead the product and site with the employer outcome.** Move the manifesto and + testnet wallet proof to an evidence path. +3. **Offer a no-wallet, no-key sandbox that demonstrates the full loop:** import a Skill, + record use by a second person, preview attribution, and close a reward period. +4. **Build the signed ledger, policy engine, creator portfolio, and monthly close before + on-chain settlement or a marketplace.** +5. **Charge for the program, not participation or creator earnings.** Favor a platform + fee per program or business unit, with generous included event volume. + +## What is already strong + +The project has unusually good foundations for an early research repository: + +- It labels evidence as measured, modeled, or hypothesis and states plainly that employer + demand is unvalidated ([root README](../README.md)). +- It has already made the correct strategic reframe: the closed compensation layer is + the terminal product, while the marketplace is optional + ([ADR-0007](adr/0007-closed-mode-compensation-layer-as-terminal-product.md)). +- It proves the thin payer, settlement arithmetic, provenance graph, and clone-economics + questions with executable artifacts. +- The Pi-Wielder proof has a clear architecture and runbook + ([Pi-Wielder README](../spikes/pi-wielder/README.md)). +- The offline clone and fork-economics paths run successfully without credentials. In + this review, they passed 97 checks and 64 invariants respectively. +- The corpus records uncomfortable findings—paid failures, clone economics, context loss, + securities exposure, and the Education bypass—instead of hiding them. + +These are credibility assets. The next step is to organize them around a customer journey +rather than asking every newcomer to reconstruct the product thesis from the research +corpus. + +## The core product gap + +The accepted product direction, public experience, and funding model do not yet agree. + +| Question | Current answer | Recommended answer | +|---|---|---| +| What is the product? | ADR-0007 says intra-org compensation; the site presents a sovereignty manifesto and a paid hosted Skill. | An employer-funded Skill attribution, governance, and reward program. | +| Who buys? | Not shown. The site speaks to an unspecified wallet holder. | Head of AI Platform / DevEx, with Total Rewards or IP Operations as co-owner. | +| Who receives value? | A one-time Wielder receives one output and receipt. | Admins get portfolio governance; Creators get durable evidence and rewards; Wielders get approved Skills in existing tools. | +| Where does compensation come from? | [CONTEXT.md](../CONTEXT.md) says intra-org upside comes from external Wielders, while the marketplace may never ship. | The employer funds an internal pool; genuine external revenue uses a separate revenue-share policy. | +| What is the billable product? | A 2.5% treasury split on a $0.25 Invocation in the demo. | Annual software license plus implementation and enterprise add-ons. | +| What makes users return? | No persistent account, history, catalog, dashboard, close, or notification loop. | Adoption, feedback, maintenance, monthly reward close, and audit loops. | + +The funding contradiction is the most important product decision. A terminal intra-org +product cannot require a future external marketplace to produce the employee benefit it +promises. + +## Recommended product contract + +### Initial customer profile + +Treat this as a hypothesis to validate, not a settled market fact: + +- An AI-forward software, professional-services, or knowledge-work company. +- Roughly 100–2,000 employees, large enough to have reusable internal AI artifacts but + small enough to run a design-partner program without a multi-year transformation. +- A centralized AI platform, developer-productivity, or automation team. +- A growing inventory of prompts, Skills, agents, plugins, or workflow automations. +- An existing innovation award, inventor award, bonus, or employee-recognition budget is + a strong qualification signal. + +The ideal buying group is: + +| Role | Job to be done | +|---|---| +| Head of AI Platform / DevEx | Find, govern, distribute, and measure reusable AI Skills. | +| VP Engineering / CIO | Show AI productivity and retain high-leverage contributors. | +| Total Rewards / People | Run a consistent, budgeted creator-recognition program. | +| Legal / IP / Finance | Approve ownership, departure, dispute, and payout rules. | +| Employee-Creator | Prove authorship and impact; receive recognition or compensation. | +| Employee-Wielder | Use approved Skills with almost no new workflow. | + +The creator is the beneficiary of the promise, but the employer has the budget and the +administrative problem. + +### The minimum durable workflow + +```text +Import → verify authorship → publish internally → use in existing tools + → collect outcome evidence → review attribution → close reward period + → notify Creator → improve/version Skill → more trusted reuse +``` + +The Phase-1 product should include: + +1. **Organization workspace** + - Organization, user, team, and role model. + - SSO or directory identity for enterprise deployments. + - Admin, policy reviewer, Creator, and viewer permissions. + +2. **Skill registry** + - Import from GitHub or a supported Skill directory. + - Canonical Skill ID, version hash, Creator, co-Creators, maintainer, status, and + lineage. + - Review, approve, deprecate, transfer maintainership, and archive flows. + - Searchable internal catalog with install or usage instructions. + +3. **Organization-native meter** + - Adapters for the customer's existing model gateway, agent runtime, or CLI. + - No individual wallet for internal use. + - Customer-hosted or VPC execution when repository or tool context is required. + - x402 only at the external payment edge. + +4. **Signed evidence ledger** + - Durable, idempotent Invocation records. + - Organization, Skill and version, Creator policy, Wielder or service identity, + timestamp, success, latency, cost, outcome signal, source, and adjustment status. + - Append-only policy and attribution history. + - No raw prompt or output storage by default; support redaction, hashing, retention + limits, and customer-controlled storage. + +5. **Reward policy and close** + - Fixed employer budget by month or quarter. + - Configurable weights, caps, eligibility, vesting, clawback, termination, and + co-authorship. + - Provisional allocation, anomaly review, manager/HR approval, dispute workflow, and + CSV/payroll export. + - Plain-language creator statement explaining why an award was calculated. + +6. **Creator and admin views** + - Creator: adoption, repeat users, teams reached, feedback, versions, maintenance + alerts, and provisional reward. + - Admin: active portfolio, duplication, failures, outcome evidence, budget, policy, + pending approvals, and audit export. + +ADR-0007 already identifies vesting, clawback, and termination as first-class design +inputs. They should be part of the core domain model, not postponed until a marketplace. + +## Resolve compensation without rewarding spam + +Use an Invocation as an evidence event, not as a dollar counter. + +The repository measured one human prompt producing seven paid agent turns +([Pi-Wielder results](../spikes/pi-wielder/README.md#measured-results--overhead-distribution--live-pi-session-2026-07-15)). +A literal per-call reward therefore favors chatty runtimes, creates unpredictable employer +cost, and is easy to game. + +For internal use: + +1. The employer commits a fixed reward budget for a period. +2. Successful uses create provisional evidence points. +3. The policy weights signals such as unique Wielders, second-team adoption, repeat use, + accepted output, a linked downstream artifact, quality, and maintenance. +4. Caps and anomaly detection limit loops, retries, self-use, and synthetic traffic. +5. An authorized reviewer approves the close. +6. Payroll or the employer's reward system delivers the award. + +For genuine external revenue, a separate policy can split actual collected revenue. Do +not mix an internal recognition award and an external royalty into one unexplained +balance. + +This keeps the premise—Creators retain an economic claim on reuse—while making the +closed-mode product viable without a public marketplace. + +## Onboarding review and enhancements + +### 1. Align the first 15 seconds with the accepted product + +The public site currently asks a visitor to absorb ten manifesto principles before the +interactive proof and then presents a wallet, faucet, and testnet payment flow +([site content](../site/app/content.ts), +[manifesto UI](../site/app/manifesto.tsx)). That is memorable brand work, but it does not +explain the employer workflow in ADR-0007. + +Recommended homepage hierarchy: + +1. **Outcome:** “Measure and reward the people who build the AI workflows your company + reuses.” +2. **Proof:** a three-panel view of a registered Skill, verified team use, and creator + award statement. +3. **Role paths:** + - Employer: “Run a design-partner pilot.” + - Creator: “See what your Skill portfolio could look like.” + - Platform team: “Inspect the meter and event schema.” +4. **No-wallet interactive sandbox.** +5. **Technical receipts and manifesto.** + +Keep “Never Handed Over” as a strong campaign or evidence page. It should not carry the +entire product onboarding job. + +### 2. Replace the first paid experience with a truthful free one + +The public Skill promises to inspect a repository and resolve actual files, patterns, and +verification commands +([Skill source](../site/app/api/invoke/%5BskillId%5D/skill.md)). The API sends only a text +input and the Skill prompt to a model; it provides no repository, files, search tools, or +execution tools +([invoke route](../site/app/api/invoke/%5BskillId%5D/route.ts)). + +That means the paid first experience cannot reliably fulfill the Skill's defining +contract. + +Choose one: + +- Use a genuinely stateless demonstration Skill that is valuable from pasted input alone; + or +- Let the user connect a repository or use a preloaded sample repository, and execute with + the tools the Skill requires. + +The recommended sandbox should use a seeded fictional company: + +1. Choose or import a sample Skill. +2. Confirm its Creator and version. +3. Simulate use by three teammates. +4. Mark one result as accepted and link one sample pull request. +5. Show the creator-impact view and reward preview. + +Only after that should an interested technical evaluator opt into the wallet/testnet +protocol proof. + +### 3. Give each persona a first-five-minutes path + +| Persona | First success | Target | +|---|---|---| +| Buyer | Completes the sandbox and sees a sample monthly close. | Under 3 minutes | +| Organization admin | Imports one Skill, sets a sample policy, and records use by a second person. | Under 10 minutes | +| Creator | Claims authorship and sees one attributed use and reward explanation. | Under 5 minutes | +| Technical evaluator | Runs every offline proof from one root command. | Under 5 minutes after install | +| Contributor | Finds current architecture, roadmap, issues, and verification commands. | Under 10 minutes | + +### 4. Create a repository-wide paved road + +The root currently has no workspace manifest, pinned Node version, CI workflow, or single +verification command. The four proofs require directory hopping, and +[`site/README.md`](../site/README.md) is still the generated Next.js starter text. The +site has required environment variables but no committed `.env.example`. + +Recommended repository changes: + +- Add pinned Node/npm versions. +- Add root commands such as `bootstrap`, `verify`, `demo:offline`, and `site:mock`. +- Use `npm ci` consistently where a lockfile exists. +- Add `site/.env.example` and a zero-key `dev:mock` mode. +- Add CI for offline proofs, Phase 0 tests/typecheck, and site lint/build/tests. +- Replace the deliberately failing `prototype` test script. +- Print an expected success transcript and elapsed time. +- Add `docs/START_HERE.md`, `docs/ARCHITECTURE.md`, `docs/ROADMAP.md`, and + `CONTRIBUTING.md`. +- Publish sanitized product requirements instead of repeatedly referring contributors to + an unpublished PRD. + +### 5. Make paid failures explicit and recoverable + +The repository measured paid upstream failures and a settled-but-rejected payment with no +output. The live route also settles before execution and can return a paid receipt with an +error. The UI throws before preserving that error receipt +([hook](../site/app/components/useInvoke.ts), +[route](../site/app/api/invoke/%5BskillId%5D/route.ts)). + +Before encouraging repeat paid use: + +- Preserve and display the receipt on every failure. +- Represent uncertain settlement as `payment_status: unknown`, not “nothing charged.” +- Add a durable idempotency key and Invocation state machine. +- Issue an automatic retry credit or refund after post-settlement failure. +- Validate configuration, input, and upstream readiness before authorization. +- Expose success rate, paid-without-output rate, refund time, and reconciliation errors. +- Do not show a declared split as if it were a completed payout. The current route settles + to one `payTo` address and returns a static split; creator balances and reconciliation + need their own ledger. + +For future external payments, current x402 documentation also describes usage-capped and +batch-settlement schemes. Evaluate those instead of treating the prototype's v1 fixed-price +path as a permanent product constraint +([x402 seller quickstart](https://docs.x402.org/getting-started/quickstart-for-sellers)). + +### 6. Add basic return actions + +The current public output is ephemeral React state. Add: + +- Saved Invocation and receipt history. +- Copy, download, rerun, feedback, and share actions. +- A next step after success. +- A design-partner/contact CTA. +- Funnel instrumentation from page view through repeat successful use. + +## Retention: why organizations and people stay + +The durable product is a set of reinforcing loops, not a payment handshake. + +### Creator improvement loop + +```text +Attributed use → outcome feedback → Creator sees impact → updates Skill + → Wielders adopt the new version → more verified value +``` + +Build version-specific feedback, update prompts, release notes, adoption lift, and stale +dependency alerts. + +### Team adoption loop + +```text +One Creator publishes → teammate succeeds → internal proof spreads + → another team adopts → more Creators contribute +``` + +Build a searchable catalog, clear install instructions, featured Skills, related Skills, +team invitations, and cross-team milestones. + +### Compensation ritual + +```text +Monthly evidence → policy calculation → reviewer approval → creator statement + → reward delivered → continued contribution and maintenance +``` + +This is the most defensible retention loop because it becomes an operational program, not +a novelty dashboard. A monthly close, audit trail, payroll export, and dispute process make +the system costly to replace for legitimate reasons. + +### Governance loop + +```text +Portfolio evidence → identify valuable, duplicate, stale, or risky Skills + → assign action → improve portfolio quality → trust grows +``` + +Add owner-departure alerts, duplicate detection, deprecated-version use, policy exceptions, +and maintainership transfer. + +### Return triggers + +- Weekly Creator digest: new users, teams, feedback, milestone, and update prompt. +- Monthly admin impact and reward-close report. +- First-five-users and first-second-team milestones. +- Declining-success and stale-version alerts. +- New-version notification for Wielders. +- Quarterly portfolio and policy review. + +Do not rely on a leaderboard alone. It will amplify popularity and gaming unless it is +quality-adjusted and reviewed. + +## Metrics + +### North star + +Use **weekly verified uses of shared Skills in retained organizations**. + +A verified use should be successful, performed by someone other than only the Creator, +and carry either an acceptance signal or a downstream outcome reference. Raw Invocation +count is a diagnostic, not the north star. + +### Activation + +- Visitor-to-sandbox-start and sandbox-completion rate. +- Sandbox-to-pilot-request rate. +- Time to first imported Skill. +- Time to first successful use by a second person. +- Percentage of workspaces that preview a reward policy. +- Percentage of pilot organizations activated within 14 days. + +### Engagement and retention + +- W1, W4, and W12 active-organization retention. +- Seven- and 28-day repeat-Wielder rate. +- Percentage of registered Skills used by at least two people and two teams. +- Verified uses per active organization. +- 30- and 90-day Skill survival. +- Monthly reward-close completion. +- Department expansion and invited-user conversion. + +### Creator loop + +- Active Creators per organization. +- Percentage receiving actionable feedback. +- Version update rate and adoption lift after update. +- Provisional, approved, and delivered compensation. +- Creator dashboard return rate. +- Perceived-recognition and intent-to-continue signals. + +### Buyer value + +- Estimated time or cost saved, with confidence level shown. +- Reward pool as a percentage of approved value. +- Duplicate or unowned Skills resolved. +- Pilot-to-paid conversion. +- Renewal and business-unit expansion. + +### Reliability and trust + +- Successful Invocation rate. +- Paid-without-output rate. +- Retry-credit or refund completion time. +- Ledger/payment reconciliation error rate. +- Attribution and policy dispute rate. +- p50/p95 time to first useful output. + +Employee-retention impact will take months to establish. Early proxies are continued +Creator participation, update frequency, cross-team reuse, perceived recognition, and +intent-to-stay changes. + +## Monetization + +### Why the current take rate should not be the business + +The prototype's 2.5% treasury fee yields $0.00625 on a $0.25 Invocation. + +| Volume | Creator/payment volume | Protocol revenue | +|---:|---:|---:| +| 100,000 Invocations | $25,000 | $625 | +| 1,000,000 Invocations | $250,000 | $6,250 | +| 4,000,000 Invocations | $1,000,000 | $25,000 | +| 160,000,000 Invocations | $40,000,000 | $1,000,000 | + +That is a poor base for enterprise implementation, security, support, and a compensation +workflow. It also creates the wrong optics: a creator-sovereignty product funds itself by +skimming creator rewards. + +Payment settlement is becoming low-cost infrastructure. Coinbase currently lists its x402 +facilitator at 1,000 free transactions per month and $0.001 thereafter +([official pricing](https://docs.cdp.coinbase.com/x402/core-concepts/facilitator)). +The attributed longitudinal ledger and policy workflow—not the payment handshake—must be +the premium. + +### Recommended revenue model + +#### 1. Annual enterprise program license + +Charge the employer for: + +- Skill registry and version/lineage system. +- Signed evidence ledger. +- Policy and reward-close workflow. +- Creator and administrator analytics. +- Audit, privacy, security, and export controls. + +Price by program or business unit with unlimited employee participants. Include a generous +event allowance; use event overages only to cover material infrastructure cost. + +This avoids penalizing adoption and matches an adjacent innovation-platform pattern. +Wazoku lists a $15,000-per-admin annual license with unlimited end users +([official pricing](https://www.wazoku.com/total-innovation-license/)). + +#### 2. Paid implementation and managed program services + +Offer: + +- Skill inventory and data mapping. +- Event-source integration. +- Reward-policy design and workflow configuration. +- Identity, HRIS, and payroll export setup. +- Admin training and first-close support. + +Wazoku separately lists enhanced onboarding at $5,450 and onboarding plus program setup at +$12,000, which supports treating implementation as real work rather than burying it in +software margin. + +#### 3. Enterprise add-ons + +- VPC, hybrid, or customer-managed data plane. +- SSO, SCIM, advanced RBAC, and longer audit retention. +- HRIS/payroll integrations. +- Custom policy packs and multi-jurisdiction workflows. +- SLA, premium support, and managed reconciliation. + +#### 4. OEM or metering API + +After the product works directly, sell the attributed meter to IP-management, +compensation, AI-gateway, or developer-platform vendors. This may become a strong channel +because those vendors already own buyer relationships but generally meter invention +milestones rather than runtime AI-asset use. + +#### 5. Benchmark analytics, later + +With explicit customer consent and strong aggregation thresholds, offer benchmarks for +Skill adoption, reward policy, creator concentration, maintenance, and reuse. This should +be an opt-in add-on only after enough customers make the data meaningful. + +#### 6. External marketplace fee, deferred + +If the product later supplies discovery, demand, collections, refunds, quality control, +and trust, test a 5–10% fee on external revenue. Do not charge that fee merely for wrapping +an endpoint in x402, and do not build tradeable claims without specialist legal advice. + +### Pricing hypotheses to test + +These are starting offers for design conversations, not validated prices: + +| Offer | Hypothesis | +|---|---:| +| Founding design-partner pilot, 8–12 weeks | $10,000–$20,000 | +| Single-program annual license | $15,000–$30,000 | +| Multi-business-unit annual license | $40,000–$75,000 | +| Enterprise/private deployment | $75,000–$150,000+ | +| Implementation | $5,000–$15,000 | +| Managed program support | $2,000–$5,000/month | + +Useful adjacent anchors as of the review date: + +- AppColl lists Invention Manager at $350/month for 100 users, including award + management, SSO, HR integration, workflows, and analytics + ([official pricing](https://www.appcoll.com/corporation-product-pricing/)). +- Bonusly lists employee-recognition software at $30–$50 per user annually and explicitly + separates the software subscription from rewards redeemed at face value + ([official pricing](https://bonusly.com/pricing)). +- LangSmith combines a team subscription with metered usage and reserves hybrid, + self-hosted, SSO, RBAC, and SLA capabilities for enterprise + ([official pricing](https://www.langchain.com/pricing)). +- Stripe Billing lists 0.7% of billing volume or annual subscription tiers, an additional + signal that mature metering infrastructure does not justify a 2.5% fee by itself + ([official pricing](https://stripe.com/billing/pricing)). + +These products are not exact competitors. They bound how buyers already purchase adjacent +innovation, recognition, observability, and billing workflows. + +### What not to monetize first + +- Do not charge Creators to register or see their own evidence. +- Do not take a percentage of an employer's internal reward pool. +- Do not make token sales or tradeable royalty claims the funding plan. +- Do not make the Education model a paid offer until its free re-authoring bypass has a + measured counter. +- Do not rely on inference resale margin; the repository already recognizes it as + commoditizing. + +## Validation plan + +### Customer discovery + +Run 12–15 interviews across: + +- AI Platform / Developer Productivity. +- Engineering or technology executives. +- Total Rewards / People Operations. +- IP Operations, Legal, or Finance. + +Prioritize organizations that already operate an inventor, innovation, or recognition +program and already have a centralized AI gateway or internal Skill inventory. + +Questions should test existing behavior, not solicit compliments: + +- How are reusable AI workflows found, approved, and maintained today? +- Who gets credit when another team reuses one? +- Has lack of credit caused hoarding, duplicated work, or attrition risk? +- What budget funds inventor awards, spot bonuses, or innovation programs? +- Which evidence would make an award defensible? +- Who can approve policy and payment? +- What security or employment-law condition would stop a pilot? +- Would the company fund a pool even if no external customer ever invokes a Skill? + +### Paid concierge pilot + +Do not wait for a full platform: + +1. Import a real Skill inventory. +2. Ingest signed or reconciled events from one existing runtime. +3. Produce creator and admin views, even if some operations are manual. +4. Run one policy preview and two monthly closes. +5. Export a payroll-ready or award-ready file. +6. Measure cross-team adoption, disputes, admin time, and Creator response. + +### Decision gates + +| Hypothesis | Pass signal | If it fails | +|---|---|---| +| Employers will pay for the rail. | Three pilots at $10,000 or more. | Stop protocol expansion; narrow or abandon the B2B thesis. | +| Internal compensation does not require marketplace revenue. | At least one pilot funds a real Creator pool. | Reposition as governance/analytics or target only commercialized Skills. | +| Usage evidence can approximate value. | Admins agree that the highest-scored Skills overlap materially with their independently selected high-value set. | Change signals and policy; do not automate payouts. | +| The buying group can form. | Each pilot has an AI-platform champion and a Total Rewards/IP owner. | Narrow to one buyer's problem and remove cross-functional scope. | +| Context-bound Skills can be instrumented usefully. | A meaningful share of one customer's real inventory produces reliable versioned events without losing its useful context. | Change the asset class or execution model. | +| The program creates a habit. | Two monthly closes complete and W4 verified use persists. | Diagnose workflow value before adding more integrations. | +| Annual value supports enterprise pricing. | Two pilots convert at $25,000+ ARR. | Reduce scope/cost or test an OEM model. | + +These are product decision gates, not forecasts. + +## Prioritized roadmap + +### Now: 0–30 days + +1. Write an ADR resolving the intra-org funding source and scoping “the Wielder is a + wallet” to external payment flows. +2. Run the customer interviews and recruit paid design partners. +3. Rewrite the primary landing page around the employer outcome. +4. Add a no-wallet seeded sandbox and a clear pilot CTA. +5. Replace or properly tool-enable the current demo Skill. +6. Fix charged-failure receipt visibility and define retry-credit/refund semantics. +7. Add a root offline verification path and replace the site starter README. +8. Publish a public product overview, architecture, roadmap, and contribution path. + +### Pilot: 31–90 days + +1. Define the organization, Skill/version, event, policy, close, and dispute schemas. +2. Import Skills from one source and events from one real runtime. +3. Build a persistent signed ledger. +4. Deliver minimal Creator and admin views. +5. Run fixed-budget policy previews and CSV/payroll export. +6. Instrument activation, verified use, trust, and close metrics. +7. Complete the first paid pilot close. + +### Productize: 91–180 days + +1. Add multi-tenant workspaces, SSO, RBAC, and identity mapping. +2. Add the internal catalog, versioning, feedback, and maintainer workflows. +3. Add configurable policies, approvals, departures, and disputes. +4. Add reliability controls, idempotency, credits/refunds, and reconciliation. +5. Add weekly Creator and monthly admin return triggers. +6. Offer customer-hosted or VPC execution for context-sensitive Skills. +7. Convert pilots to annual contracts. + +### Only after the gates pass + +- Background or opt-in Story registration. +- Additional runtime adapters. +- OEM/API distribution. +- Opt-in benchmark analytics. +- External x402 monetization. +- Marketplace discovery or tradeable claims, subject to legal review. + +### Explicitly defer + +- Securities and transfer infrastructure. +- Open marketplace build-out. +- Education-mode commercialization. +- TEE investment for an unvalidated open market. +- More inference-reseller work that does not improve the attributed ledger. + +## Bottom line + +The premise is monetizable, but not primarily as a per-call royalty marketplace. + +The commercially coherent product is the system an employer uses to answer: + +- What reusable AI Skills do we have? +- Who created and maintains them? +- Which teams use them successfully? +- What value evidence can we defend? +- What policy determines recognition or compensation? +- What changed, who approved it, and what was paid? + +If the project can make that monthly operating loop trustworthy and easy, the existing +wallet, provenance, and settlement work becomes valuable optional infrastructure. If it +cannot find three employers willing to pay for that loop, more protocol depth will not +solve the core problem. diff --git a/site/.env.example b/site/.env.example new file mode 100644 index 0000000..b4fb432 --- /dev/null +++ b/site/.env.example @@ -0,0 +1,22 @@ +# Optional: destination for the employer-facing design-partner CTA. +# Defaults to a prefilled GitHub issue when unset. +NEXT_PUBLIC_PILOT_CONTACT_URL= + +# Optional proof-route seller configuration. +# The primary product page and its seeded sandbox need none of these. + +# Explicit safety switch. Keep false until persistent rate limits and an +# Anthropic spend cap are configured for this deployment. +ENABLE_PAID_PROOF=false + +# Base Sepolia address that receives the proof route's testnet USDC. +PAY_TO_ADDRESS= + +# Seller-side model key used only after a proof-route payment settles. +ANTHROPIC_API_KEY= + +# x402 v1 testnet facilitator used by the preserved proof endpoint. +FACILITATOR_URL=https://x402.org/facilitator + +# Never put a production wallet key in this site. The browser proof asks an +# injected wallet to sign a scoped testnet authorization; it stores no key. diff --git a/site/.gitignore b/site/.gitignore index 5ef6a52..870462f 100644 --- a/site/.gitignore +++ b/site/.gitignore @@ -12,6 +12,8 @@ # testing /coverage +/output/playwright/ +/.playwright-cli/ # next.js /.next/ @@ -32,6 +34,7 @@ yarn-error.log* # env files (can opt-in for committing if needed) .env* +!.env.example # vercel .vercel diff --git a/site/README.md b/site/README.md index e215bc4..ef1d546 100644 --- a/site/README.md +++ b/site/README.md @@ -1,36 +1,76 @@ -This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app). +# Skill Asset Protocol site -## Getting Started +The site has two deliberately separate paths: -First, run the development server: +- `/` is the employer-facing product preview and deterministic attribution + sandbox. It needs no account, wallet, API key, network call, or payment. +- `/proof` preserves the original manifesto and optional Base Sepolia x402 + invocation proof. + +## Local product preview + +Use Node 22. The production dependency graph and image optimizer are verified +against that major. ```bash +npm ci npm run dev -# or -yarn dev -# or -pnpm dev -# or -bun dev ``` -Open [http://localhost:3000](http://localhost:3000) with your browser to see the result. +Open . The full seeded sandbox works with no environment +file and never calls the payment or model API. + +The sample organization, people, Invocations, outcome evidence, and provisional +reward are fictional. Refreshing or choosing **Restart sandbox** returns to the +same deterministic fixture. + +## Optional configuration -You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file. +Copy the template only when you need to change the pilot CTA or operate the +testnet proof: -This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel. +```bash +cp .env.example .env.local +``` -## Learn More +| Variable | Required for `/` | Required for paid `/proof` invocation | +|---|---:|---:| +| `NEXT_PUBLIC_PILOT_CONTACT_URL` | No | No | +| `ENABLE_PAID_PROOF=true` | No | Yes | +| `PAY_TO_ADDRESS` | No | Yes | +| `ANTHROPIC_API_KEY` | No | Yes | +| `FACILITATOR_URL` | No | No (testnet default provided) | -To learn more about Next.js, take a look at the following resources: +The proof path uses testnet USDC only. Use a throwaway testnet wallet and never +put a wallet private key in the site environment. Paid proof invocation is +disabled by default because free testnet funds can still trigger real model +spend. Keep it disabled until the deployment has persistent rate limiting and +an Anthropic spend cap. -- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API. -- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial. +## Verification -You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome! +```bash +npm test +npm run lint +npm run build +npm audit --omit=dev +``` -## Deploy on Vercel +`npm test` covers the sandbox fixture and transition guards with Node's built-in +test runner. The build must pass without secrets because `/` is an offline +product preview; the proof API validates its seller configuration at request +time. The production audit is expected to report zero vulnerabilities. See the +[dependency security audit](../docs/dependency-security-audit.md) for the +remaining dev-only advisory and the intentionally pinned transitive fixes. -The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js. +## Relevant files -Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details. +| Path | Role | +|---|---| +| `app/page.tsx` | Employer-facing landing page composition | +| `app/landing.module.css` | Industrial product-page design system | +| `app/components/landing/AttributionSandbox.tsx` | Client-only sandbox UI | +| `app/components/landing/sandbox-model.ts` | Deterministic fixture and reducer | +| `app/components/InvokeControls.tsx` | Wallet/invocation client island on `/proof` | +| `app/proof/page.tsx` | Preserved manifesto and x402 proof route | +| `app/api/invoke/[skillId]/route.ts` | Optional testnet Collar endpoint | diff --git a/site/app/api/invoke/[skillId]/route.ts b/site/app/api/invoke/[skillId]/route.ts index 9efa7bf..8988bfb 100644 --- a/site/app/api/invoke/[skillId]/route.ts +++ b/site/app/api/invoke/[skillId]/route.ts @@ -24,6 +24,7 @@ import { NextResponse } from 'next/server'; import { SKILL_CONTENT } from './skill-content'; export const runtime = 'nodejs'; +export const maxDuration = 60; // --- x402 v1 / Base Sepolia constants (mirror x402-seller.mjs) --------------- const X402_VERSION = 1; @@ -37,6 +38,11 @@ const SPLIT = { creator: 0.24375, treasury: 0.00625 }; // 97.5 / 2.5 of $0.25 const KNOWN_SKILL_ID = 'optimizing-claude-code-prompts'; const DEFAULT_FACILITATOR = 'https://x402.org/facilitator'; +const EVM_ADDRESS = /^0x[a-fA-F0-9]{40}$/; +const MAX_INPUT_CHARS = 4_000; +const MAX_REQUEST_BYTES = 16_384; +const FACILITATOR_TIMEOUT_MS = 10_000; +const ANTHROPIC_TIMEOUT_MS = 45_000; const jsonToB64 = (o: unknown) => Buffer.from(JSON.stringify(o)).toString('base64'); const b64ToJson = (s: string): T => JSON.parse(Buffer.from(s, 'base64').toString('utf8')) as T; @@ -62,6 +68,7 @@ async function postJson(url: string, body: unknown): Promise { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body), + signal: AbortSignal.timeout(FACILITATOR_TIMEOUT_MS), }); return res.json().catch(() => null); } @@ -75,11 +82,18 @@ export async function POST( return NextResponse.json({ error: `unknown skill: ${skillId}` }, { status: 404 }); } + if (process.env.ENABLE_PAID_PROOF !== 'true') { + return NextResponse.json( + { error: 'paid proof invocation is disabled for this deployment' }, + { status: 503 }, + ); + } + // -- config: fail honestly BEFORE taking anyone's money ----------------------- const payTo = process.env.PAY_TO_ADDRESS; - if (!payTo) { + if (!payTo || !EVM_ADDRESS.test(payTo) || /^0x0{40}$/i.test(payTo)) { return NextResponse.json( - { error: 'seller misconfigured: PAY_TO_ADDRESS is not set' }, + { error: 'seller misconfigured: PAY_TO_ADDRESS must be a nonzero EVM address' }, { status: 500 }, ); } @@ -93,6 +107,14 @@ export async function POST( const facilitatorUrl = process.env.FACILITATOR_URL || DEFAULT_FACILITATOR; // -- input: validate before challenging (don't charge for an unrunnable call) -- + const contentLength = Number(req.headers.get('content-length') ?? '0'); + if (Number.isFinite(contentLength) && contentLength > MAX_REQUEST_BYTES) { + return NextResponse.json( + { error: `request body exceeds ${MAX_REQUEST_BYTES} bytes` }, + { status: 413 }, + ); + } + let input = ''; try { const body = (await req.json()) as { input?: unknown }; @@ -106,6 +128,12 @@ export async function POST( { status: 400 }, ); } + if (input.length > MAX_INPUT_CHARS) { + return NextResponse.json( + { error: `input must be ${MAX_INPUT_CHARS} characters or fewer` }, + { status: 413 }, + ); + } const requirements: PaymentRequirements = { scheme: 'exact', @@ -205,6 +233,7 @@ export async function POST( system: SKILL_CONTENT, // the protected asset stays server-side messages: [{ role: 'user', content: input }], }), + signal: AbortSignal.timeout(ANTHROPIC_TIMEOUT_MS), }); if (!anthropicRes.ok) { diff --git a/site/app/components/InvokeControls.tsx b/site/app/components/InvokeControls.tsx new file mode 100644 index 0000000..caa1137 --- /dev/null +++ b/site/app/components/InvokeControls.tsx @@ -0,0 +1,164 @@ +'use client'; + +import { useState } from 'react'; + +import { useInvoke, type InvokeState } from './useInvoke'; + +const STATES: { key: InvokeState; label: string }[] = [ + { key: 'idle', label: 'IDLE' }, + { key: 'connecting', label: 'CONNECTING' }, + { key: 'paying', label: 'PAYING' }, + { key: 'running', label: 'RUNNING' }, + { key: 'done', label: 'DONE' }, + { key: 'error', label: 'ERROR' }, +]; + +const STATUS_LINE: Record = { + idle: 'AWAITING INSTRUCTION. NOTHING SIGNED, NOTHING SENT.', + connecting: 'CONNECTING WALLET — SWITCHING CHAIN TO BASE SEPOLIA.', + paying: '402 RECEIVED — SIGN, DON’T SEND. THE FACILITATOR SETTLES.', + running: 'PAYMENT SETTLED — SKILL EXECUTING. OUTPUT INBOUND.', + done: 'DELIVERED. YOU GOT THE OUTPUT. THE SKILL STAYED HOME.', + error: 'STOPPED. SEE INCIDENT REPORT BELOW.', +}; + +const shortTx = (tx: string) => `${tx.slice(0, 10)}…${tx.slice(-8)}`; + +export function InvokeControls({ basescan }: { basescan: string }) { + const { state, output, paid, error, account, connect, invoke, needsWallet } = + useInvoke(); + const [input, setInput] = useState(''); + const busy = + state === 'connecting' || state === 'paying' || state === 'running'; + + return ( + <> +
+

+ FIELD 04 — SIGNATORY (STEP 01: CONNECT A WALLET) +

+ {account ? ( +

+ CONNECTED — {shortTx(account)} · BASE SEPOLIA +

+ ) : ( + + )} +
+ +
+ +