jh1nresh · Sep 9, 2026 · Sep 8, 2026
diff --git a/.env.example b/.env.example
@@ -0,0 +1,12 @@
+# Local development only. Copy to .env and replace with your own values.
+# Create this disposable PostgreSQL database before running Prisma schema setup.
+DATABASE_URL="postgresql://postgres:postgres@localhost:5432/agentshack_dev"
+NEXT_PUBLIC_APP_URL="http://localhost:3000"
+
+# Your development Privy app ID is required for wallet/auth UI.
+NEXT_PUBLIC_PRIVY_APP_ID=""
+# Server-side Privy verification only. Never use a NEXT_PUBLIC_ prefix for secrets.
+PRIVY_APP_SECRET=""
+
+# No private keys, production credentials, relayer or settlement flags are supplied.
+# This file does not change the fixed BSC Testnet marketplace configuration.
diff --git a/.gitignore b/.gitignore
@@ -1,6 +1,7 @@
 node_modules
 .next
 .env*
+!.env.example
 *.log
 *.patch
 *.diff

diff --git a/HACKATHON.md b/HACKATHON.md
@@ -2,6 +2,8 @@
 
 A BSC Testnet marketplace for discovering, inspecting and hiring curated BNB Agent Studio agents across all four main-track categories.
 
+[Project overview](README.md) · [Development](docs/development.md) · [Documentation](docs/README.md)
+
 - Track: Main Track — Build the BNB Agent Studio Marketplace.
 - Repository: https://github.com/jh1nresh/agentshack
 - Public marketplace: https://www.agentshack.io/market
@@ -30,8 +32,8 @@ The marketplace lists third-party Studio Desk services. The descriptions above d
 3. Open its setup page and connect a BSC Testnet wallet.
 4. Request a signed quote. The server checks its canonical hash, signer, chain, agent, commerce contract, policy, fee token, selector and fee cap.
 5. Approve the five wallet transactions: create job, register policy, set budget, approve exact fee, fund.
-6. Request delivery. Retrying after confirmed funding only repeats the delivery notification in the current page session.
-7. Inspect the seller response and transaction links. Record delivery and actual execution evidence separately.
+6. Request delivery. My agents (`/dashboard`) and Activity (`/activity`) retain wallet-scoped records in the same browser. Recovery verifies the original successful create/fund transactions before retrying notification, without creating another payment.
+7. Inspect the seller response and transaction links. Record delivery and actual execution evidence separately. Partial/replaced transactions require manual review; history is not imported from older sessions without saved records or other devices. Notification retry is not an exactly-once guarantee.
 
 The wallet needs testnet BNB for gas and the seller's quoted test $U token. The four currently listed fees total 0.0042 test $U, excluding gas. The app does not acquire tokens or send a private key to a server.
 
@@ -65,7 +67,7 @@ Use https://testnet.bscscan.com to inspect these addresses and each transaction.
 - Unit/property tests cover changed identities, endpoint paths, wrong chain/payment targets, modified quote terms, invalid signatures, fee bounds, malformed payloads, oversized streams and funded-job retry decisions.
 - Funded-hire evidence: pending selection of the buyer wallet and its signatures. No new funded job or delivery is claimed by this document.
 - Deployment must be confirmed against `/api/health` and the deployed commit; a successful build alone is not deployment evidence.
-- Registration/submission confirmation: not found in the checked inbox. Confirm an existing response before submitting again.
+- Registration/submission confirmation: not established by repository or CI evidence. Confirm an existing response before submitting again.
 
 For each category, record buyer address, job ID, quote hash, all five transaction hashes, seller response, and any resulting execution transaction. A response saying accepted/pending is not completed execution.
 

diff --git a/README.md b/README.md
diff --git a/contracts/README.md b/contracts/README.md
@@ -1,83 +1,45 @@
-# Dojo Contracts
+# Contracts
 
-On-chain contracts for the Maiat Dojo — Agent Skill Marketplace.
+[AgentShack overview](../README.md) · [Documentation](../docs/README.md)
 
-## Contracts
+Solidity sources and Foundry tests retained by AgentShack / Maiat Dojo. This directory is **not** the source of every third-party contract used by the BNB marketplace.
 
-| Contract | Description |
-|----------|-------------|
-| **SkillNFT** | ERC-1155 skill tokens with USDC auto-split (85% creator / 10% platform / 5% reputation pool) |
-| **SkillRoyaltySplitter** | Agent Services payment split (80% operator / 15% creator / 5% platform) |
-| **ISkillNFT** | Shared interface for cross-contract reads |
+## Three distinct boundaries
 
-## Deployments
+| Surface | Configuration / source |
+| --- | --- |
+| Curated BNB marketplace | [`bnb-marketplace.ts`](../src/lib/bnb-marketplace.ts) and [`bnb-marketplace-activation.ts`](../src/lib/bnb-marketplace-activation.ts); chain 97, third-party registry/seller/commerce integration |
+| Dojo receipt and settlement engine | [`contracts.ts`](../src/lib/contracts.ts); separate addresses and mainnet placeholders |
+| Local Solidity code | [`src/`](src/): registry, job, reputation, token, royalty and swap components retained across product iterations |
 
-### Base Sepolia (Testnet)
+Do not interchange these contract addresses. The [hackathon guide](../HACKATHON.md#testnet-contracts) documents the marketplace targets; source configuration remains authoritative.
 
-| Contract | Address |
-|----------|---------|
-| SkillNFT | [`0x52635F45b087c1059B3a997fb089bae5Db095B74`](https://sepolia.basescan.org/address/0x52635F45b087c1059B3a997fb089bae5Db095B74) |
-| SkillRoyaltySplitter | [`0x98D34100F6030DFDc1370fB45dFa1Ad7980D4bD8`](https://sepolia.basescan.org/address/0x98D34100F6030DFDc1370fB45dFa1Ad7980D4bD8) |
-| USDC (Circle testnet) | [`0x036CbD53842c5426634e7929541eC2318f3dCF7e`](https://sepolia.basescan.org/address/0x036CbD53842c5426634e7929541eC2318f3dCF7e) |
+## Build and test (no transactions)
 
-### Base Mainnet
-
-TBD — deploy after testnet validation.
-
-## Build & Test
+Install Foundry and the exact dependency revisions pinned by the [CI workflow](../.github/workflows/ci.yml). In a fresh checkout, from the repository root:
 
 ```bash
+git clone https://github.com/foundry-rs/forge-std.git contracts/lib/forge-std
+git -C contracts/lib/forge-std checkout --detach 0844d7e1fc5e60d77b68e469bff60265f236c398
+git clone https://github.com/OpenZeppelin/openzeppelin-contracts.git contracts/lib/openzeppelin-contracts
+git -C contracts/lib/openzeppelin-contracts checkout --detach 5fd1781b1454fd1ef8e722282f86f9293cacf256
 cd contracts
-forge build       # compile
-forge test        # 56 tests (43 unit + 13 fuzz)
-forge test -vvv   # verbose output
+forge build --sizes
+forge test -vv
 ```
 
-## Deploy
-
-```bash
-# Base Sepolia
-PRIVATE_KEY=0x... forge script script/Deploy.s.sol --rpc-url base-sepolia --broadcast
-
-# Base Mainnet
-PRIVATE_KEY=0x... forge script script/Deploy.s.sol --rpc-url base --broadcast
-```
+If dependencies already exist, inspect their revisions and changes rather than overwriting them. `forge build` and this test suite are verification commands, not a deployment procedure. Use CI logs for current test counts.
 
-Optional: set `BASESCAN_API_KEY` in env and uncomment `[etherscan]` in `foundry.toml` for contract verification.
-
-## Architecture
-
-```
-SkillNFT (ERC-1155 + ERC-2981 + ISkillNFT)
-├── createSkill()     — Owner lists a skill (price, creator, royaltyBps, URI)
-├── buySkill()        — Anyone pays USDC → auto-split → mint NFT
-├── setSkillActive()  — Owner activates/deactivates
-├── setFees()         — Atomic fee update (platform + reputation pool)
-└── rescueTokens()    — Emergency fund recovery
-
-SkillRoyaltySplitter
-├── pay()             — Service payment → 80/15/5 split (operator/creator/platform)
-│   ├── Operator must hold skill NFT (M-3)
-│   ├── Skill must be active (L-4)
-│   ├── Pull-then-push pattern (M-2)
-│   └── MIN_AMOUNT enforced (Lead)
-├── setFeeSplit()     — Adjust split (operator ≥ 50%)
-└── rescueTokens()    — Emergency fund recovery
-```
+## Deployment and operational safety
 
-## Security
+- [`foundry.toml`](foundry.toml) currently defines `bsc` and `bsc_testnet` RPC aliases.
+- The root [Makefile](../Makefile) still has legacy Base deploy/interaction targets. They are not supported instructions for this marketplace.
+- [`script/`](script/) contains state-changing deployment and seed scripts. No broadcast, signer/role change or settlement is authorized by following this README.
+- Marketplace hires are approved by the user's BSC Testnet wallet. Mainnet entries in the retained Dojo configuration include zero-address placeholders and must not be presented as ready.
+- The [release policy](../config/maiat-release-policy.json) separates app readiness from contract broadcast and chain writes.
 
-- **Audited** by Jensen (Slither + Trail of Bits skills) + Patrick (Pashov parallel 8-agent audit)
-- 5 findings resolved (3 Medium + 2 Low) + 6 leads addressed
-- Full audit reports: [`contracts/audits/`](./audits/)
-- ReentrancyGuard on all payment functions
-- Pull-then-push pattern prevents USDC blacklist DoS
-- Operator NFT ownership verified on every service payment
+## Security and historical references
 
-## Key Design Decisions
+[`audits/`](audits/) contains dated reports for specific code and review scopes. Their presence is not a current security certification, a formal third-party audit of the marketplace, or an audit of Studio Desk sellers.
 
-- **USDC only** — no native ETH, no oracle dependency, minimal attack surface
-- **No funds held** — contract distributes immediately, nothing to steal
-- **Atomic fee updates** — prevents non-atomic misconfiguration
-- **MIN_PRICE / MIN_AMOUNT** — prevents dust/spam transactions
-- **royaltyBps** is ERC-2981 only (secondary market); Agent Services uses global split
+The former Base deployment table, SkillNFT split descriptions and original audit claims are preserved in [legacy Base contract notes](../docs/archive/legacy-base-contracts.md), clearly separated from current setup.
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,37 @@
+# Documentation
+
+[AgentShack overview](../README.md) is the public starting point. This index separates the current marketplace from the retained workflow engine and historical plans.
+
+## Current guides
+
+| Guide | Use it for |
+| --- | --- |
+| [Hackathon overview](../HACKATHON.md) | Four categories, service limits, testnet addresses and outstanding evidence |
+| [Local development](development.md) | npm, PostgreSQL, Privy, checks and release boundaries |
+| [Workflow integrations](workflows.md) | Older REST, creator CLI and MCP surfaces |
+| [Contracts](../contracts/README.md) | Source boundaries, read-only Foundry verification and legacy deployment warnings |
+| [Creator CLI](../packages/dojo-cli/README.md) | Local workflow manifest commands |
+| [MCP server](../packages/dojo-mcp/README.md) | Local stdio tools and configuration |
+
+## Configuration sources
+
+- [Curated agents](../src/lib/bnb-marketplace.ts) and [seller quote targets](../src/lib/bnb-marketplace-activation.ts) define the marketplace's testnet integration.
+- [Dojo chain configuration](../src/lib/contracts.ts) belongs to the retained receipt/settlement engine; do not substitute its commerce addresses into marketplace quotes.
+- [Prisma schema](../prisma/schema.prisma), [package scripts](../package.json), [CI](../.github/workflows/ci.yml) and [release policy](../config/maiat-release-policy.json) define runtime/setup behavior.
+- [Agent instructions](../AGENTS.md) and the [PR template](../.github/pull_request_template.md) describe engineering boundaries.
+
+## Historical material
+
+- [Marketplace visual baseline](design/agentshack-marketplace/README.md): approved black/yellow direction, with older fixture-based screenshots; not current runtime evidence.
+- [April 2026 spec index](archive/spec-index-2026-04-27.md): preserved planning snapshot, including references to local-only notes.
+- [Legacy Base contracts](archive/legacy-base-contracts.md): original deployment/architecture notes; not BSC instructions or current deployment proof.
+- [Tracked specifications](../specs/) and [changelog](../CHANGELOG.md): historical plans and release notes. Check implementation and commit-bound evidence before treating claims as current.
+- [Contract audit reports](../contracts/audits/): dated, scoped reports, not certification of the current marketplace or third-party sellers.
+
+## Compatibility files retained
+
+`package.json` and CI select npm. The older `pnpm-lock.yaml` is retained for history, not a second supported install procedure. This documentation change does not regenerate dependencies.
+
+The root `Makefile` still contains legacy Base broadcast targets, while current Foundry aliases are BSC. Use the explicit read-only checks in the contract guide; do not use those deploy targets for the BNB marketplace.
+
+Some `specs/` files were committed before that directory was ignored. Existing tracked files remain in Git; an ignore rule is not a privacy boundary. No local-only notes are imported by this documentation cleanup.
diff --git a/docs/archive/legacy-base-contracts.md b/docs/archive/legacy-base-contracts.md
@@ -0,0 +1,88 @@
+# Legacy Dojo Base Contracts — Historical Notes
+
+> Archived original documentation. Base addresses, broadcast commands, test counts
+> and audit claims below are historical and are not verified current instructions.
+> Do not execute the deployment examples for the BNB marketplace. Use the
+> [current contract guide](../../contracts/README.md) instead.
+
+On-chain contracts for the Maiat Dojo — Agent Skill Marketplace.
+
+## Contracts
+
+| Contract | Description |
+|----------|-------------|
+| **SkillNFT** | ERC-1155 skill tokens with USDC auto-split (85% creator / 10% platform / 5% reputation pool) |
+| **SkillRoyaltySplitter** | Agent Services payment split (80% operator / 15% creator / 5% platform) |
+| **ISkillNFT** | Shared interface for cross-contract reads |
+
+## Deployments
+
+### Base Sepolia (Testnet)
+
+| Contract | Address |
+|----------|---------|
+| SkillNFT | [`0x52635F45b087c1059B3a997fb089bae5Db095B74`](https://sepolia.basescan.org/address/0x52635F45b087c1059B3a997fb089bae5Db095B74) |
+| SkillRoyaltySplitter | [`0x98D34100F6030DFDc1370fB45dFa1Ad7980D4bD8`](https://sepolia.basescan.org/address/0x98D34100F6030DFDc1370fB45dFa1Ad7980D4bD8) |
+| USDC (Circle testnet) | [`0x036CbD53842c5426634e7929541eC2318f3dCF7e`](https://sepolia.basescan.org/address/0x036CbD53842c5426634e7929541eC2318f3dCF7e) |
+
+### Base Mainnet
+
+TBD — deploy after testnet validation.
+
+## Build & Test
+
+```bash
+cd contracts
+forge build       # compile
+forge test        # 56 tests (43 unit + 13 fuzz)
+forge test -vvv   # verbose output
+```
+
+## Deploy
+
+```bash
+# Base Sepolia
+PRIVATE_KEY=0x... forge script script/Deploy.s.sol --rpc-url base-sepolia --broadcast
+
+# Base Mainnet
+PRIVATE_KEY=0x... forge script script/Deploy.s.sol --rpc-url base --broadcast
+```
+
+Optional: set `BASESCAN_API_KEY` in env and uncomment `[etherscan]` in `foundry.toml` for contract verification.
+
+## Architecture
+
+```
+SkillNFT (ERC-1155 + ERC-2981 + ISkillNFT)
+├── createSkill()     — Owner lists a skill (price, creator, royaltyBps, URI)
+├── buySkill()        — Anyone pays USDC → auto-split → mint NFT
+├── setSkillActive()  — Owner activates/deactivates
+├── setFees()         — Atomic fee update (platform + reputation pool)
+└── rescueTokens()    — Emergency fund recovery
+
+SkillRoyaltySplitter
+├── pay()             — Service payment → 80/15/5 split (operator/creator/platform)
+│   ├── Operator must hold skill NFT (M-3)
+│   ├── Skill must be active (L-4)
+│   ├── Pull-then-push pattern (M-2)
+│   └── MIN_AMOUNT enforced (Lead)
+├── setFeeSplit()     — Adjust split (operator ≥ 50%)
+└── rescueTokens()    — Emergency fund recovery
+```
+
+## Security
+
+- **Audited** by Jensen (Slither + Trail of Bits skills) + Patrick (Pashov parallel 8-agent audit)
+- 5 findings resolved (3 Medium + 2 Low) + 6 leads addressed
+- Full audit reports: [`contracts/audits/`](../../contracts/audits/)
+- ReentrancyGuard on all payment functions
+- Pull-then-push pattern prevents USDC blacklist DoS
+- Operator NFT ownership verified on every service payment
+
+## Key Design Decisions
+
+- **USDC only** — no native ETH, no oracle dependency, minimal attack surface
+- **No funds held** — contract distributes immediately, nothing to steal
+- **Atomic fee updates** — prevents non-atomic misconfiguration
+- **MIN_PRICE / MIN_AMOUNT** — prevents dust/spam transactions
+- **royaltyBps** is ERC-2981 only (secondary market); Agent Services uses global split
diff --git a/SPECS.md → docs/archive/spec-index-2026-04-27.md b/SPECS.md → docs/archive/spec-index-2026-04-27.md
@@ -1,7 +1,8 @@
-# Maiat Dojo — Spec Index
+# Maiat Dojo — Historical Spec Index (April 27, 2026)
 
-> Auto-read this file FIRST when entering the repo to avoid re-discovering existing work.
-> Last updated: 2026-04-27
+> Preserved planning snapshot, not current product or release status. Start with the
+> [AgentShack README](../../README.md) and [documentation index](../README.md).
+> Local `~/brain` references and dated PR statuses below are historical, not public links or current instructions.
 
 ---
 

diff --git a/docs/design/agentshack-marketplace/README.md b/docs/design/agentshack-marketplace/README.md
@@ -1,6 +1,10 @@
 # BNB Agent Marketplace UI lock
 
-Status: approved visual direction, demo-data implementation.
+Status: historical approved visual baseline (fixture-data stage). The black/yellow
+direction remains relevant, but these screenshots are not current runtime proof.
+The source now includes curated testnet agents and wallet-approved hiring; see the
+[current overview](../../../README.md) and [hackathon guide](../../../HACKATHON.md).
+The flow, fixture restrictions and capture claims below describe the original UI lock.
 
 ## Product flow