Add LocalAgentCore product wedge and x402-paid API publisher

.dockerignore

@@ -0,0 +1,26 @@
+.git
+.gitignore
+.dockerignore
+.pytest_cache
+.mypy_cache
+.ruff_cache
+__pycache__
+node_modules
+dist
+.next
+.vinext
+.wrangler
+lecore-site
+*.py[cod]
+*.pyo
+.venv
+venv
+env
+.env
+.env.*
+metrics
+holostuff.zip
+current backlogs
+*_backlog.md
+PANEL_*_backlog.md
+RENDER_PIPELINE_BACKLOG.md

API_QUICKREF.md

@@ -1,6 +1,48 @@
 # leCore API Quick Reference
 
-*A scannable, one-line-per-symbol map of the app-building surface -- auto-generated by `apiquickref.py` on 2026-07-12. For the full engine (every module), see REFERENCE.md.*
+*A scannable, one-line-per-symbol map of the app-building surface -- auto-generated by `apiquickref.py` on 2026-07-14. For the full engine (every module), see REFERENCE.md.*
+
+## Product wedge
+
+### `holographic_product`
+*holographic_product.py -- the small product-facing leCore facade.*
+
+- **class `MemoryEntry`** -- One stored memory item.
+    - `to_dict(self)` -- Return a JSON-safe representation of this memory entry.
+    - `from_dict(cls, data)` -- Build a memory entry from `to_dict` data.
+- **class `LocalAgentCore`** -- Product facade for local agent memory, skill routing, and evidence.
+    - `entries(self)` -- A copy of the stored entries, in insertion order.
+    - `remember(self, text, label=None, metadata=None, id=None)` -- Store one local memory.
+    - `remember_many(self, items)` -- Store several memories.
+    - `recall(self, query, k=3, abstain=None)` -- Return the nearest stored memories for `query`, best first.
+    - `suggest(self, task, k=5)` -- Suggest capabilities for a plain-English task.
+    - `route(self, task)` -- Route a task to one capability when confident, otherwise return options.
+    - `evidence(self)` -- Return a machine-readable product readiness snapshot.
+    - `dashboard(self, html=False)` -- Return the evidence dashboard as a dict, or static HTML with `html=True`.
+    - `dashboard_html(data)` -- Render an evidence snapshot as a dependency-free static HTML dashboard.
+    - `to_state(self)` -- Serialize configuration and entries.
+    - `from_state(cls, state)` -- Rebuild a core from `to_state` data.
+    - `save(self, path)` -- Write the product state to JSON and return the path.
+    - `load(cls, path)` -- Load a product state saved by `save`.
+- `demo()` -- Build a tiny ready-to-query product demo.
+
+### `holographic_x402_api`
+*holographic_x402_api.py -- publish LocalAgentCore as an x402-paid API.*
+
+- **class `PaidRoute`** -- One x402-protected route.
+    - `key(self)` -- The route key shape expected by x402 middleware, e.g.
+- **class `X402Config`** -- Seller configuration for the x402-paid API.
+    - `from_env(cls, require_pay_to=True)` -- Build config from LECORE_X402_* environment variables.
+    - `to_public_dict(self)` -- Public, JSON-safe view of the payment configuration.
+- `optional_dependency_help()` -- Install hint for the optional paid API dependencies.
+- `leos_token_offer()` -- Public metadata for the leOS CA-only offer.
+- `landing_page_html(config)` -- Render the buyer-facing landing page served from `/`.
+- `payment_manifest(config)` -- Plain JSON route manifest, useful for docs, `/pricing`, and tests.
+- `x402_route_configs(config)` -- Build x402 SDK RouteConfig objects for the protected routes.
+- `x402_resource_server(config)` -- Create an x402 resource server wired to the configured facilitator.
+- `create_app(core=None, config=None, paid=True, admin_token=None, state_path=None)` -- Create the FastAPI app.
+- `load_core(path)` -- Load a persisted core if present, otherwise return the demo core.
+- `main(argv=None)` -- CLI entry point for local x402 API serving.
 
 ## Scene authoring
 

AWS_X402_DEPLOY.md

@@ -0,0 +1,161 @@
+# AWS x402 Deployment
+
+> **Note:** the default deploy path is Fly.io — see
+> [`FLY_X402_DEPLOY.md`](FLY_X402_DEPLOY.md). This doc remains as the AWS
+> alternative; its wallet-storage guidance is provider-agnostic.
+
+This is the production shape for serving `LocalAgentCore` as an x402-paid API
+on AWS.
+
+## Short Answer
+
+Yes, we can launch this on AWS. For the **seller** side of x402, the service
+does **not** need a wallet private key in the container. It only needs:
+
+- the public receiving wallet address (`LECORE_X402_PAY_TO`)
+- x402/facilitator configuration
+- an admin token for seller-only memory writes
+
+The receiving wallet should be a cold wallet, hardware wallet, Safe/multisig,
+or a custody wallet. The API simply tells x402 where funds should go.
+
+Only build an AWS-hosted signing wallet if the app itself must **spend** funds
+or pay upstream APIs as a buyer.
+
+## Recommended AWS Architecture
+
+- **ECS Fargate** runs the `Dockerfile.x402` container.
+- **Application Load Balancer** terminates HTTPS and forwards to port `4021`.
+- **ECR** stores the container image.
+- **Secrets Manager** stores `LECORE_X402_ADMIN_TOKEN` and production
+  facilitator credentials.
+- **SSM Parameter Store or plain task env** stores non-secret config like
+  `LECORE_X402_PAY_TO`, `LECORE_X402_PRICE`, and `LECORE_X402_NETWORK`.
+- **CloudWatch Logs** captures service logs.
+- **AWS WAF** can rate-limit and block bad traffic at the ALB.
+
+Protected paid routes:
+
+- `POST /v1/recall`
+- `POST /v1/route`
+- `GET /v1/dashboard`
+
+Free routes:
+
+- `GET /health`
+- `GET /pricing`
+
+Seller-only route:
+
+- `POST /admin/remember`, guarded by `X-Admin-Token`
+
+## Build And Push
+
+```bash
+aws ecr create-repository --repository-name lecore-x402
+
+ACCOUNT_ID="$(aws sts get-caller-identity --query Account --output text)"
+REGION="${AWS_REGION:-us-west-2}"
+IMAGE="$ACCOUNT_ID.dkr.ecr.$REGION.amazonaws.com/lecore-x402:latest"
+
+aws ecr get-login-password --region "$REGION" \
+  | docker login --username AWS --password-stdin "$ACCOUNT_ID.dkr.ecr.$REGION.amazonaws.com"
+
+docker build -f Dockerfile.x402 -t "$IMAGE" .
+docker push "$IMAGE"
+```
+
+## Runtime Environment
+
+Non-secret environment variables:
+
+```text
+LECORE_X402_PAY_TO=0xYourReceivingWallet
+LECORE_X402_PRICE=$0.001
+LECORE_X402_NETWORK=eip155:8453
+LECORE_X402_FACILITATOR_URL=https://api.cdp.coinbase.com/platform/v2/x402
+```
+
+Secrets Manager values:
+
+```text
+LECORE_X402_ADMIN_TOKEN=<random admin token>
+CDP_API_KEY_ID=<if required by facilitator setup>
+CDP_API_KEY_SECRET=<if required by facilitator setup>
+```
+
+Use ECS task definition `secrets` entries for secrets, not literal environment
+variables in the task definition.
+
+## Wallet Storage Decision
+
+### Seller API, Recommended
+
+Do **not** store a private key in AWS.
+
+The API receives payments; it does not spend. x402 payment verification and
+settlement happen through the facilitator. The service only advertises
+`payTo`.
+
+Best receiving wallet options:
+
+- Safe/multisig
+- hardware wallet
+- cold wallet
+- custodial account dedicated to receipts
+
+### Buyer/Spender API, If Needed Later
+
+If the leCore agent itself needs to pay other x402 APIs, use a separate signer
+service:
+
+1. Create an AWS KMS asymmetric signing key with `ECC_SECG_P256K1`.
+2. Derive the public Ethereum address from `kms:GetPublicKey`.
+3. Allow only a narrow IAM role to call `kms:Sign`.
+4. Sign EIP-712/EIP-3009 payload digests through KMS.
+5. Enforce spend limits in application logic before every signing request.
+6. Log every signing request with CloudTrail and app-level audit records.
+
+This keeps the private key non-exportable: it never appears in the container.
+
+### High-Assurance Signer
+
+For larger balances or stronger isolation, put the signing service in **AWS
+Nitro Enclaves** and allow KMS decrypt/sign only when enclave attestation
+matches the expected image measurement.
+
+### Last Resort
+
+Storing a raw private key in Secrets Manager is acceptable only for testnet or
+very small hot-wallet balances. If used, wrap it with strict IAM, rotation
+plans, spend limits, CloudTrail alarms, and a tiny blast radius.
+
+## First Production Checklist
+
+- Use mainnet network id and production facilitator URL.
+- Put the ALB behind HTTPS only.
+- Keep `/admin/remember` private or blocked from the public ALB path.
+- Keep paid route configs explicit; avoid wildcard paid routes at first.
+- Add WAF rate limits.
+- Add CloudWatch alarms on 5xx, 402 spikes, and admin write attempts.
+- Keep customer memory isolated before offering paid writes.
+- Do not put secrets or PII in x402 route descriptions or payment metadata.
+
+## Local Smoke Before AWS
+
+```bash
+pip install ".[x402]"
+export LECORE_X402_PAY_TO="0xYourReceivingWallet"
+export LECORE_X402_ADMIN_TOKEN="local-admin-secret"
+python holographic_x402_api.py --unpaid-dev --host 127.0.0.1 --port 4021
+```
+
+Then:
+
+```bash
+curl http://127.0.0.1:4021/health
+curl http://127.0.0.1:4021/pricing
+curl -X POST http://127.0.0.1:4021/v1/route \
+  -H "Content-Type: application/json" \
+  -d '{"task":"search local agent memory"}'
+```

CAPABILITIES.md

@@ -288,6 +288,14 @@ import lecore; m=lecore.UnifiedMind(dim=256,seed=0); print(m.suggest_pipeline('t
 ```
 *Find it by:* how do I get from points to a mesh, chain capabilities, build a pipeline, route between datatypes, what steps turn X into Y
 
+### x402 paid API publisher
+publish the LocalAgentCore product wedge as a paid HTTP API: FastAPI routes for recall, task routing, and the evidence dashboard protected by x402 middleware, with free health/pricing routes and admin-token-gated memory writes..
+
+```python
+from holographic_x402_api import create_app, X402Config; app = create_app(config=X402Config(pay_to='0x...'))
+```
+*Find it by:* x402, paid api, payment required, 402, monetize api, micropayment, agent payments, pay per request
+
 ## Memory, search & recall
 
 *store things and get them back by CONTENT, not by exact key.*
@@ -390,6 +398,14 @@ mind.navigator_benchmark()              # recall + the fixed-beam baseline
 ```
 *Find it by:* navigator, adaptive search, learned search, search a tree, nearest neighbour search, beam search, spend less effort on easy queries, reflex cache
 
+### Local agent core (memory + routing)
+the PRODUCT-FACING wedge: LocalAgentCore gives a local agent deterministic text memory (remember/recall), skill routing over the live capability catalog, JSON persistence, and a readiness dashboard with C-kernel status. This is the small stable door for embedding leCore without learning the whole research surface first..
+
+```python
+from holographic_product import LocalAgentCore; core = LocalAgentCore(); core.remember('local agent memory'); core.recall('agent memory')
+```
+*Find it by:* product, productization, agent memory, local memory, durable memory, recall, skill routing, dashboard
+
 ### Memoize a pure function (the purity gate is the point)
 skip re-execution of PURE work whose inputs repeat. mind.memoize_pure(fn) keys on (the function's EXACT canonical source, its arguments) and REFUSES a function that is not pure -- is_pure rejects the clock, RNG, IO, global writes, and transitive impurity through a call-graph fixpoint, while accepting a locally-allocated container. A cache over an impure function returns a stale answer silently, so the gate raises instead. MEASURED: 36x on a repeated 256x256 SVD, bit-identical. THE BACKLOG CALLS THIS 'shape-keyed memoization', AND THAT NAME IS A BUG: a canonical shape erases identifiers and constants, so `def f(x): return x + 1` and `def g(x): return x + 2` have the SAME shape and would share a cache entry. mind.canonical_shape(fn) exists, and is a COMPRESSION primitive, never a cache key. KEPT NEGATIVE: the key costs O(input bytes) -- fingerprinting a 512x512 array costs 1.747 ms while A.sum() costs 0.084 ms, so a cheap function of a large array loses 21x; ask mind.machine_place with the function's own cost as the baseline. TWO BACKLOG NUMBERS DID NOT REPRODUCE: shape reuse is 1.13x (node type + depth) or 1.87x (control flow), not 2.36x -- it is a property of the equivalence relation, not the code; and tree purity is 35.4% (781 of 2,188 module-level functions), not 76%. HONEST SCOPE: the gate resolves callees within ONE module, so a function that calls an IMPORTED helper is refused as unresolved (sound, and why tucker.rank_gate is rejected -- it reaches fix_eigvec_signs from another module). Cross-module resolution wants types..
 
@@ -2461,4 +2477,4 @@ import numpy as np; import lecore; m=lecore.UnifiedMind(dim=256,seed=0); x=np.li
 
 ---
 
-*308 capability homes. Regenerate this file with `python capdoc.py` (it reads the live catalog, so it stays in step with the engine).*
+*310 capability homes. Regenerate this file with `python capdoc.py` (it reads the live catalog, so it stays in step with the engine).*

Dockerfile.x402

@@ -0,0 +1,15 @@
+FROM python:3.12-slim
+
+ENV PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1
+
+WORKDIR /app
+
+COPY . /app
+
+RUN python -m pip install --no-cache-dir --upgrade pip \
+    && python -m pip install --no-cache-dir ".[x402]"
+
+EXPOSE 4021
+
+CMD ["python", "holographic_x402_api.py", "--host", "0.0.0.0", "--port", "4021"]

FLY_X402_DEPLOY.md

@@ -0,0 +1,85 @@
+# Fly.io x402 Deployment
+
+This is the default production shape for serving `LocalAgentCore` as an
+x402-paid API. It uses `Dockerfile.x402` and `fly.x402.toml`; no cloud-specific
+code changes are needed. (For the AWS variant and the full wallet-storage
+discussion, see [`AWS_X402_DEPLOY.md`](AWS_X402_DEPLOY.md) — the wallet
+guidance there is provider-agnostic and applies here too.)
+
+## Seller Security Model
+
+Same as the AWS doc's short answer: the seller side needs **no private key**
+in the container. It only needs:
+
+- the public receiving wallet address (`LECORE_X402_PAY_TO`)
+- x402/facilitator configuration
+- an admin token for seller-only memory writes
+
+Use a cold wallet, hardware wallet, or Safe/multisig as the receiving address.
+
+## First Deploy (testnet)
+
+```bash
+fly launch --config fly.x402.toml --no-deploy   # creates the app, keeps our config
+fly volumes create lecore_data --config fly.x402.toml --size 1
+
+# Secrets first: the app fails loud on boot without a pay-to address.
+fly secrets set --config fly.x402.toml \
+  LECORE_X402_PAY_TO="0xYourReceivingWallet" \
+  LECORE_X402_ADMIN_TOKEN="$(openssl rand -hex 24)"
+
+fly deploy --config fly.x402.toml
+```
+
+Verify:
+
+```bash
+curl https://lecore-x402.fly.dev/health
+curl https://lecore-x402.fly.dev/pricing
+# Paid route must answer 402 with a `payment-required` challenge header:
+curl -si https://lecore-x402.fly.dev/v1/dashboard | head -5
+```
+
+Seed seller memory (writes persist to the volume via `LECORE_X402_STATE`):
+
+```bash
+curl -X POST https://lecore-x402.fly.dev/admin/remember \
+  -H "Content-Type: application/json" \
+  -H "X-Admin-Token: <your admin token>" \
+  -d '{"text":"local agents need deterministic durable memory","label":"memory"}'
+```
+
+## Custom Domain
+
+```bash
+fly certs add lecore.rati.foundation --config fly.x402.toml
+```
+
+Point DNS at the app, then set `LECORE_X402_PUBLIC_URL` in `fly.x402.toml` to
+the custom domain so the landing page and `/pricing` advertise the right
+endpoint.
+
+## Mainnet Flip
+
+The defaults are Base Sepolia + the signup-free x402.org testnet facilitator,
+which does **not** settle real funds. To charge real USDC on Base:
+
+```toml
+LECORE_X402_NETWORK = "eip155:8453"
+LECORE_X402_FACILITATOR_URL = "https://api.cdp.coinbase.com/platform/v2/x402"
+```
+
+The CDP facilitator requires Coinbase Developer Platform credentials — check
+the current x402/CDP docs for the auth shape and set any required keys with
+`fly secrets set`, never in `fly.x402.toml`. Re-verify the `payment-required`
+challenge advertises `eip155:8453` before announcing the endpoint.
+
+## Production Checklist
+
+- Mainnet network id + production facilitator before announcing.
+- Receiving address is cold/multisig, never a hot key in the container.
+- `LECORE_X402_ADMIN_TOKEN` set via `fly secrets`, rotated if shared.
+- Volume mounted and `LECORE_X402_STATE` set, or accept that admin writes
+  reset to the demo core on every restart.
+- Keep paid route configs explicit; no wildcard paid routes.
+- No secrets or PII in route descriptions or payment metadata.