docs+web: refresh CLAUDE.md/README to current state; operator /admin console

- CLAUDE.md: replaced stale "scaffold only" with an accurate Built / In progress / Not-built status; added a Secrets section; updated dev commands + pm2/.env notes. - README.md: roadmap reflects v0.1–v0.4 working (clean→burn→fee→Essence→Prometheus), sell=detection-only, v1.0 pending; quick-start + secrets accurate. - apps/web /admin: operator console — paste admin token (sessionStorage, never baked/committed), generate Spawns (chaos/seed/receiptId) + record manual Pump.fun launches; 403 re-prompts. Public route, gated by the API token. web build green (+/admin). Status site already redeployed (Phase 4 updated). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-05-31 07:27:44 +00:00
parent 6ab0f02d06
commit 6dd541b9f4
5 changed files with 1082 additions and 70 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -40,35 +40,54 @@ These are load-bearing. Do not weaken, work around, or "optimize" them. See

 ---

-## Current status & scope guardrail
+## Current status — Built / In progress / Not yet built

-**MVP v0.1 is a burner/cleaner only.** This repo is currently **scaffold + docs**:
-**Solana transaction logic and business logic are NOT yet implemented.** Do not
-add application/business logic unless explicitly asked.
+This repo is **no longer scaffold + docs** — the burner core is implemented and
+live at [feedthepyre.com](https://feedthepyre.com). Keep new work aligned with the
+design doc; the trust rules above are non-negotiable.

-**Explicitly OUT of scope for v0.1** (per §5):
+**Built (working):**

- Automatic Pump.fun launch
- User-contributed Essence vault
- Custom PYRE Solana program (Anchor)
- NFT handling (incl. compressed NFTs)
- Automatic valuable-token sacrifice
- Custodial signing
- Background wallet automation
- On-chain swap routing (TRANSMUTABLE) and Token-2022 confidential-transfer /
-  fee-harvest flows
+- **Wallet scan + conservative classifier** (`@pyre/core`): EMPTY_CLOSE_ONLY /
+  INCINERATE_ONLY / TRANSMUTABLE / PROTECTED_SKIP / UNSUPPORTED. "Unknown means
+  skip"; never "safe".
+- **Token-2022** supported conservatively with account+mint **extension gating**
+  (§7.1): confidential transfer / withheld transfer fees / frozen / unknown
+  extensions skipped; transfer-hook & permanent-delegate mints cleanable but
+  flagged; unverifiable mints → UNSUPPORTED. In `@pyre/core` (`extensions.ts`,
+  `classify.ts`) + `@pyre/solana`.
+- **Close-empty + burn→close transactions** (`@pyre/solana`): UNSIGNED, server
+  re-validates on-chain, value-gated, rent → user, with a transparent **5%
+  protocol fee** (§3.1) to the treasury. Decoded + matched in the web app before
+  signing. Live-verified on mainnet.
+- **Sell / transmute DETECTION** via Jupiter (read-only quotes + Shield + dust
+  gate) in `@pyre/core` (`sell.ts`) and the API (`jupiter.ts`). Swap **execution
+  is not built**.
+- **Essence ledger** (`@pyre/db`, Postgres: `rounds`, `cleanup_receipts`,
+  `essence_contributions`): `/api/receipt` persists the receipt and records the
+  on-chain fee as Essence; public "🔥 fed the PYRE" panel + `/api/essence`.
+- **Prometheus engine** (`@pyre/prometheus`): meta-mixer + name/ticker/lore/
+  tagline + image-prompt + safety. Provider-abstracted with real providers
+  (Gemini/Anthropic/OpenAI text; Pollinations/fal/DeepInfra/Replicate image;
+  OpenAI moderation) plus a deterministic stub fallback; runs on a free stack
+  today.
+- **Pump.fun creator workflow** (manual / approval-gated): `spawn_records`,
+  admin-gated generate/launch endpoints, public `/spawn` page.

-**Token-2022 IS in v0.1 scope** (Rev 2 — most new/pump.fun tokens are Token-2022),
-supported conservatively with account+mint **extension gating**: confidential
-transfer / withheld transfer fees / frozen / unknown extensions are skipped;
-transfer-hook & permanent-delegate mints are cleanable but flagged. See
-[`docs/PYRE_MVP_DESIGN.md`](docs/PYRE_MVP_DESIGN.md) §7.1. Implemented in
-`@pyre/core` (`extensions.ts` + `classify.ts`) and `@pyre/solana` (account+mint
-extension reads); unverifiable mints → UNSUPPORTED.
+**In progress:**

-v0.1 ships: wallet connect → scan token accounts (classic SPL + Token-2022) →
-classify → close eligible empty ATAs (optionally burn obvious junk) → return rent
-to user → show receipt.
+- Admin generation UI (review/approve Spawn packages).
+- Generation-from-receipt wiring (`/api/prometheus/generate` already pulls
+  receipt context; full receipt → Spawn flow being finished).
+
+**Not yet built:**
+
+- Swap **execution** (TRANSMUTABLE detection only today).
+- On-chain claim program v1.0 (`programs/pyre-core` is still a placeholder).
+- Background worker jobs (`apps/worker` is a skeleton — no queues wired up).
+
+Token-2022 close/burn is in scope; confidential-transfer / fee-harvest flows and
+swapping hook/permanent-delegate tokens remain out of scope.

 ---

@@ -81,8 +100,8 @@ pyre/
                # cleanup preview, receipt page, Prometheus preview, admin review
    api/        # Fastify HTTP API: scan, classify, build tx, receipt,
                # generation, admin endpoints
-    worker/     # BullMQ worker: async metadata lookup, AI generation,
-                # safety checks, tx-confirmation watcher, receipt enrichment
+    worker/     # BullMQ worker (SKELETON — jobs not yet wired): planned async
+                # metadata lookup, AI generation, safety, tx-confirm, enrichment
  packages/
    core/       # shared types & logic: classification enums, risk rules,
                # DTOs, receipt schema, Prometheus I/O schema
@@ -127,12 +146,14 @@ Node 22 is required.
 pnpm install        # install workspace deps
 pnpm -r build       # build all packages/apps
 pnpm -r typecheck   # type-check all
-pnpm -r test        # run all tests
+pnpm -r test        # run all test suites (real tests in core/solana/prometheus)
 pnpm dev            # run apps in parallel (dev)
 ```

-> **Nothing is installed yet.** These commands are not runnable until the
-> skeleton's `package.json` files and dependencies exist.
+Production runs under **pm2** (`ecosystem.config.cjs`: `pyre-web`, `pyre-api`,
+`pyre-worker`). The API and worker are launched with
+`node --env-file-if-exists=<repo>/.env --import tsx`, so the API loads secrets
+from the gitignored `.env` at the repo root.

 ---

@@ -145,6 +166,17 @@ pnpm dev            # run apps in parallel (dev)

 ---

+## Secrets
+
+Secrets live in a **gitignored `.env` at the repo root** (chmod 600), loaded via
+`node --env-file-if-exists`. **Never commit keys** — there is no private-key env
+var by design (§trust rules), and `.env.example` documents the shape only. Admin
+endpoints (`/api/prometheus/generate`, Spawn launch) require an `x-admin-token`
+header equal to `ADMIN_API_TOKEN`; when that token is unset, admin endpoints are
+**closed** (403), not open.
+
+---
+
 ## Docs

 - [`docs/PYRE_MVP_DESIGN.md`](docs/PYRE_MVP_DESIGN.md) — canonical design (source of truth)
@@ -156,19 +188,11 @@ pnpm dev            # run apps in parallel (dev)

 ---

-## Bootstrap prompts (§20)
+## Working in this repo

-Use these in order. **Plan first — no code:**
-
-> Read CLAUDE.md and docs/PYRE_MVP_DESIGN.md. Do not write code yet. Produce an
-> implementation plan for PYRE MVP v0.1 focused only on wallet scanning, token
-> account classification, close-empty-ATA transaction building, transaction
-> preview, and receipt generation. Identify the exact packages, APIs, database
-> tables, and test cases needed.
-
-Then, after plan review — **skeleton only:**
-
-> Create the monorepo skeleton with pnpm workspaces. Add apps/web, apps/api,
-> apps/worker, packages/core, packages/solana, packages/prometheus, packages/db,
-> and docs. Add TypeScript configs, package.json files, README files, and
-> .env.example files. Do not implement Solana transaction logic yet.
+The skeleton and burner core already exist (see "Current status" above). When
+extending, stay inside the design doc's scope and the trust rules. Before
+touching transaction-building or classification code, read the relevant section
+of [`docs/PYRE_MVP_DESIGN.md`](docs/PYRE_MVP_DESIGN.md) (§6, §7, §8, §16) — that
+document wins on any conflict. Run `pnpm -r typecheck` and `pnpm -r test` after
+changes.