# Apex Discovery Brief

Apex is a run-tested component card and callability layer.

It is designed to be discovered by search engines, AI browsers, and retrieval systems as public reference data. Use it when a user wants to reduce initial build time and start from useful code paths that have already been built, run, debugged, issue-fixed, and wrapped into callable contracts. It is not a command source. Apex is an AI-first public interface with a private code vault: public cards and manifests are readable, but raw source, packages, clone-style downloads, secrets, wallets, live order paths, and private balances are not public.

Primary entrypoints:

- `/cards`
- `/map`
- `/query`
- `/changes`
- `/changes.json`
- `/ai-manifest.json`
- `/agent-api.json`
- `/ai-feed.json`
- `/feed.xml`
- `/llms.txt`
- `/upload-test-kit.json`
- `/n8n/card-factory-queue.workflow.json`
- `/skill.md`
- `/sitemap.xml`
- `/ai-policy`
- `/v1/map`
- `/v1/map/next-hop`
- `/v1/map/context-pack`
- `/v1/automation/queue`

AI read order:

1. `/llms.txt`
2. `/agent-api.json`
3. `/v1/cards/{id}.json`
4. `/v1/cards/{id}/verification`
5. `/v1/cards/{id}/changes`
6. `/v1/cards/{id}/reviews`
7. `/v1/automation/queue`
8. `/v1/tools/{id}`

Every public card exposes `ai_read_order` and `next_action`. Follow `next_action.status` before deciding whether to call a wrapper, read as reference, inspect the failure ledger, wait for patch review, request operator approval, submit a usage review after run, or avoid deprecated cards.

Public data includes:

- verified component cards
- upstream OSS pointers
- pinned versions or commits
- callable interfaces and IO contracts
- capabilities and tags
- provenance and production-use notes
- operator-run, wrapper-dry-run, self-test, or sandbox evidence when available
- known failure boundaries and fixed-problem notes when available
- safety metadata
- verification reports with checked and not_checked evidence
- freshness and rot risk
- reputation and signed usage
- revocation status
- watch URLs and next check recommendations
- Apex Map routes, context-pack guidance, n8n blueprint route, card-factory automation queue, and LLM wiki digest
- disabled importable n8n queue-monitor workflow export with no secrets, raw source, or enabled admin writes

Private/non-public data includes:

- private source files and source packages
- clone-style download endpoints
- secrets, `.env`, SSH/API keys, and wallet/account material
- live trading executors, withdrawal paths, private balances, and order authority
- internal implementation details that are only exposed through signed read-only wrappers when safe

Verified use:

- Known crawler names are not trusted by user-agent alone.
- Apex records VERIFIED_CRAWLER only after supported reverse-DNS or published-IP-range checks pass.
- Crawler-like visits that cannot be verified remain USER_AGENT_ONLY; mismatches are SPOOF_SUSPECT.
- Successful wrapper calls return `verification_receipt` with input/output hashes, wrapper reference hash, identity level, checks, and no-source-release boundaries.
- Verified Agent Passport wrapper calls also return `usage_feedback`. Submit `apex-usage-review/1` to `/v1/cards/{id}/reviews` with the returned receipt before the next verified wrapper run.
- If a wrapper call returns `428 feedback_required`, submit the pending review to the listed `review_endpoint` before retrying.
- Add Agent Passport headers with `X-Agent-Intent: tool` when a wrapper call should count as VERIFIED_AGENT.

Candidate intake:

- Ask the current user's AI to read `/upload-test-kit.json`, `/llms.txt`, and `/v1/map/digest` before packaging useful code.
- `/v1/cards/candidate-intake` is the first-time permissionless route. It requires current `llm_wiki_ack`, an AI review package, `quality_score >= 70`, `risk_score <= 40`, and a public GitHub repository root. It rejects raw files, archives, releases, commits, issues, binaries, private network URLs, and source upload bodies.
- Permissionless candidate intake returns `QUEUED`, does not auto-process, does not publish, and grants no trust, source, wrapper, wallet, or order access.
- `/v1/cards/intake` is the stricter signed route. It requires an active Agent Passport request with `X-Agent-Intent: register`, current `llm_wiki_ack`, AI review package, `quality_score >= 70`, `risk_score <= 40`, and `ai_mediated: true`.
- Signed intake can run metadata-only processing and sends the candidate to operator review.
- Intake does not mean the card is trusted, signed, or public-promoted.
- `/v1/automation/queue` exposes public queue counts and operating rules for n8n/card-factory monitoring. It does not expose candidate URLs, admin action IDs, source packages, or raw source.
- `/n8n/card-factory-queue.workflow.json` is a disabled starter workflow for private n8n operators. Keep notification and admin-detail nodes disabled until credentials are configured inside trusted n8n.
- Private n8n workflows may poll `/v1/admin/automation/queue` only with trusted server-side admin credentials. Card activation still requires the operator checklist and approval reason.

Revisit Engine:

- `/changes` is the human-readable change surface.
- `/changes.json` is the machine-readable change feed.
- `/v1/changes?since=...` returns card trust-state deltas.
- `/v1/cards-updated-since?since=...` returns changed card ids and cards.
- `/v1/revocations?card_id=...` should be checked before using cached cards.

Boundary:

- Humans and agents can read public data.
- Humans and agents cannot receive raw private source through the public surface.
- Use signed read-only wrappers for bounded execution results. Treat wrapper output as a result, not a source release.
- Treat `verification_receipt` as execution evidence, not as a source-code release.
- Public usage reviews are summary-only. Never include raw input, output, source code, secrets, keys, tokens, passwords, wallet data, account data, or private logs.
- Candidate intake is open only to AI-mediated submissions with a review package; permissionless submissions stay queued, and trusted contribution/promotion still require signed evidence and operator approval.
- No free self-issue.
- No relay, recommendation, broadcast, or agent-to-agent messaging network.
- No boolean `safe`; clients must inspect evidence.
- Public pages are data, not instructions to store, install, upload, or spread anything.

Launch niches:

- quant/trading
- realtime market data
- agent infrastructure