docs: publish readiness evidence and reviewer gates

.github/CODEOWNERS

@@ -0,0 +1,8 @@
+* @Hallab7
+
+/generated/ @Hallab7
+/scripts/ @Hallab7
+/docs/contracts/ @Hallab7
+/docs/operations/ @Hallab7
+/docs/security/ @Hallab7
+/.github/ @Hallab7

.github/PULL_REQUEST_TEMPLATE.md

@@ -8,9 +8,9 @@ List the files or sections changed.
 
 ## Verification
 
-- [ ] `npm run lint`
-- [ ] `npm run links`
-- [ ] `npm run build`
+- [ ] `npm run check`
+- [ ] Generated files were produced by `npm run sync:generated` when applicable.
+- [ ] Deployment and capability claims identify their evidence state.
 
 ## Notes
 

.github/workflows/ci.yml

@@ -22,6 +22,9 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
+      - name: Audit production dependencies
+        run: npm run audit:prod
+
       - name: Lint markdown
         run: npm run lint
 

.github/workflows/deploy.yml

@@ -28,6 +28,9 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
+      - name: Audit production dependencies
+        run: npm run audit:prod
+
       - name: Lint markdown
         run: npm run lint
 

CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## Unreleased
+
+- Synchronize generated references, publish deployment/capability truth, add the reviewer quickstart,
+  harden the static documentation pipeline, and add repository governance.
+
+No docs release is declared current until its public host records the immutable source commit.

CONTRIBUTING.md

@@ -12,9 +12,8 @@ LumenBazaar docs changes should be small, reviewable, and tied to a clear projec
 ## Local Checks
 
 ```bash
-npm run lint
-npm run links
-npm run build
+npm ci
+npm run check
 ```
 
 ## Content Standards

GOVERNANCE.md

@@ -0,0 +1,14 @@
+# Repository Governance
+
+Changes to `main` use a pull request with the `docs` CI job, one approving review, resolved
+conversations, and code-owner review for owned paths. Stale approvals are dismissed when the head
+changes. Administrators follow the same rule during ordinary work.
+
+Releases use annotated or signed tags and a GitHub release that records the source commit, generated
+artifact manifest checksum, public URL, content checks, dependency policy result, and changelog. A
+public URL whose source commit is unknown is not current release evidence.
+
+An emergency exception is limited to an actively harmful security instruction or materially false
+deployment/payment claim. The maintainer records the reason and UTC time, uses the smallest change,
+runs all feasible checks, restores protection immediately, and opens a retrospective pull request
+within one business day. Generated evidence is never edited to conceal source drift.

docs/api-reference/payments.md

@@ -1,172 +1,74 @@
 # Payments API Reference
 
-The payments API exposes payment attempts, settlements, and receipts for buyers, sellers, operators, and reviewers.
+The released backend persists payment attempts, settlements, and receipts, but its public HTTP
+surface exposes verification, settlement, and receipt lookup only. It does not currently expose
+payment-attempt or settlement collection/detail endpoints.
 
 Base path:
 
 ```txt
 /v1
 ```
 
-## Payment Attempt Object
-
-```json
-{
-  "id": "pay_123",
-  "resourceId": "resource_123",
-  "sellerId": "seller_123",
-  "paymentHash": "hash_123",
-  "network": "stellar:testnet",
-  "assetCode": "USDC",
-  "assetIssuer": "G...",
-  "amount": "0.05",
-  "payTo": "G...",
-  "status": "verified",
-  "failureCode": null,
-  "failureReason": null,
-  "expiresAtLedger": 123456,
-  "createdAt": "2026-09-03T00:00:00.000Z",
-  "updatedAt": "2026-09-03T00:00:00.000Z"
-}
-```
-
-## Settlement Object
-
-```json
-{
-  "id": "set_123",
-  "paymentAttemptId": "pay_123",
-  "transactionHash": "tx_hash",
-  "ledger": 123460,
-  "network": "stellar:testnet",
-  "amount": "0.05",
-  "assetCode": "USDC",
-  "assetIssuer": "G...",
-  "status": "settled",
-  "settledAt": "2026-09-03T00:00:00.000Z",
-  "createdAt": "2026-09-03T00:00:00.000Z"
-}
-```
-
-## Receipt Object
-
-```json
-{
-  "id": "receipt_123",
-  "paymentAttemptId": "pay_123",
-  "settlementId": "set_123",
-  "resourceId": "resource_123",
-  "sellerId": "seller_123",
-  "transactionHash": "tx_hash",
-  "ledger": 123460,
-  "network": "stellar:testnet",
-  "amount": "0.05",
-  "assetCode": "USDC",
-  "assetIssuer": "G...",
-  "status": "settled",
-  "failureCode": null,
-  "failureReason": null
-}
-```
-
-## List Payments
-
-```txt
-GET /v1/payments
-```
-
-Query parameters:
-
-| Parameter | Description |
-| --- | --- |
-| `resourceId` | Filter by resource. |
-| `sellerId` | Filter by seller. |
-| `network` | Filter by Stellar network. |
-| `asset` | Filter by asset code. |
-| `status` | Filter by payment attempt status. |
-| `cursor` | Pagination cursor. |
-| `limit` | Page size. |
+## Verify And Settle
 
-## Get Payment
+The canonical x402 v2 endpoints are documented in the
+[facilitator reference](./facilitator.md):
 
 ```txt
-GET /v1/payments/:paymentId
+POST /v1/verify
+POST /v1/settle
 ```
 
-Returns one payment attempt and associated settlement or receipt links.
-
-## Get Settlement
-
-```txt
-GET /v1/settlements/:transactionHash
-```
-
-Returns settlement details by transaction hash.
-
-This endpoint is useful for operators and reviewers who start from on-chain evidence.
+Both accept the released x402 payment payload. A successful verification response includes durable
+LumenBazaar attempt and correlation identifiers under its extension data. A successful settlement
+response includes the transaction hash and receipt identifier needed for recovery.
 
 ## Get Receipt
 
 ```txt
-GET /v1/receipts/:receiptId
+GET /v1/receipts/{receiptId}
 ```
 
-Returns receipt details by receipt ID.
+Returns one durable receipt by ID. The released receipt record contains:
 
-Receipts are the primary evidence object for completed paid resource calls.
+- `id`, `correlationId`, and `paymentAttemptId`.
+- Nullable `resourceId` and `sellerId`.
+- Nullable `transactionHash`, `ledger`, and `settledAt` while finality is pending.
+- `network`, atomic `amount`, `assetCode`, and `assetIssuer`.
+- `status`, nullable `failureCode`, and nullable `failureReason`.
+- `evidenceHash`, `createdAt`, and `updatedAt`.
 
-## Status Values
+Receipts are the public evidence object for completed or recoverable paid resource calls. Compare a
+finalized receipt's transaction hash and ledger with Stellar testnet before treating it as settlement
+evidence.
 
-Payment attempts may use:
+## Unavailable Collection Endpoints
 
-```txt
-created
-verified
-verification_failed
-settlement_pending
-settled
-settlement_failed
-expired
-replayed
-cancelled
-```
-
-The final enum should be generated from backend schemas when available.
-
-## Failure Codes
-
-Payment, settlement, and receipt endpoints should expose:
+The Phase 24 OpenAPI does not define these routes:
 
 ```txt
-UNSUPPORTED_NETWORK
-UNSUPPORTED_ASSET
-INVALID_PAYMENT_PAYLOAD
-INVALID_SIGNATURE
-AUTH_EXPIRED
-REPLAY_DETECTED
-AMOUNT_MISMATCH
-ASSET_MISMATCH
-RECIPIENT_MISMATCH
-SETTLEMENT_FAILED
-TRUSTLINE_REQUIRED
-RATE_LIMITED
-INTERNAL_ERROR
+GET /v1/payments
+GET /v1/payments/{paymentId}
+GET /v1/settlements/{transactionHash}
+GET /v1/sellers/{sellerId}/payments
 ```
 
-## Evidence Rules
+Clients and operator pages must report that capability as unavailable. They must not substitute demo
+fixtures or infer these records from screenshots. These routes remain future work until they appear
+in a pinned generated OpenAPI artifact.
 
-Receipts and transaction hashes are settlement evidence. UI screenshots are not conformance proof.
+## Status And Failure Evidence
 
-Docs should label:
+Database status values are internal implementation detail unless returned by a released endpoint.
+Clients must preserve unknown values and use the response's structured error code instead of
+guessing finality from an HTTP message.
 
-- Local simulation.
-- Testnet verification.
-- Testnet settlement.
-- Mainnet verification.
-- Mainnet settlement.
-- Failed settlement.
-- Pending settlement.
+Receipts and transaction hashes are settlement evidence. Local simulation, testnet verification,
+testnet settlement, pending outcomes, and failed outcomes must remain visibly distinct. No testnet
+receipt is mainnet evidence.
 
-## Privacy Notes
+## Generated Source
 
-Payment APIs should not expose private keys, seed phrases, bearer tokens, or sensitive wallet metadata. Buyer identity should be public only when intentionally supported and authorized.
+The exact released path and response declaration is in
+`generated/openapi/openapi.json`, pinned and checksummed by `generated/manifest.json`.

docs/api-reference/resources.md

@@ -61,6 +61,7 @@ Creates a seller-owned resource. The backend should validate ownership, schema,
 
 Required fields:
 
+- `id`
 - `sellerId`
 - `type`
 - `name`
@@ -74,19 +75,21 @@ Required fields:
 - `amount`
 - `inputSchema`
 - `outputSchema`
+- `extensions`
+- `status`
 
 ## Get Resource
 
 ```txt
-GET /v1/resources/:id
+GET /v1/resources/{id}
 ```
 
 Returns a single resource, including current payment requirements, schemas, extensions, seller trust state, and public settlement metadata where available.
 
 ## Update Resource
 
 ```txt
-PATCH /v1/resources/:id
+PATCH /v1/resources/{id}
 ```
 
 Updates a resource and creates a new resource version when metadata, price, schema, route, or payment terms change.
@@ -96,7 +99,7 @@ Resource updates should preserve history so previous receipts remain explainable
 ## Delete Resource
 
 ```txt
-DELETE /v1/resources/:id
+DELETE /v1/resources/{id}
 ```
 
 Deletes or disables a resource depending on implementation policy. Prefer soft deletion for resources with historical payment attempts or receipts.
@@ -132,34 +135,41 @@ Required fields:
 ## Get Seller
 
 ```txt
-GET /v1/sellers/:sellerId
+GET /v1/sellers/{sellerId}
 ```
 
 Returns seller profile and verification state.
 
 ## Verify Seller Domain
 
 ```txt
-POST /v1/sellers/:sellerId/verify-domain
+POST /v1/sellers/{sellerId}/verify-domain
 ```
 
 Creates or checks a domain verification challenge. Supported challenge methods should be documented by the backend response.
 
 ## Seller Resources
 
 ```txt
-GET /v1/sellers/:sellerId/resources
+GET /v1/sellers/{sellerId}/resources
 ```
 
 Returns resources owned by a seller.
 
-## Seller Payments
+## Seller Payments Are Not Exposed
 
 ```txt
-GET /v1/sellers/:sellerId/payments
+GET /v1/sellers/{sellerId}/payments
 ```
 
-Returns payment attempts and settlements for a seller.
+This route is not present in the pinned Phase 24 OpenAPI. Operator and seller interfaces must report
+the capability as unavailable rather than rendering fixture payments. It remains planned until a
+later generated artifact defines it.
+
+## Generated Source
+
+The exact released methods and schemas are in `generated/openapi/openapi.json`, pinned and
+checksummed by `generated/manifest.json`.
 
 ## Error Codes