Redesign README: docs-first, remove AXME intro, key documents prominent

README.md

@@ -1,48 +1,74 @@
 # axme-docs
 
-Implementation documentation, security model, API references, and architecture diagrams for the AXME platform.
+Implementation docs, API reference, security model, and architecture diagrams for the AXME platform.
 
-> **Alpha** - Protocol and API surface are stabilizing. Not recommended for production workloads yet.
-> Install CLI, log in, run your first example in under 5 minutes. [Quick Start](https://cloud.axme.ai/alpha/cli) - [hello@axme.ai](mailto:hello@axme.ai)
+[![Alpha](https://img.shields.io/badge/status-alpha-orange)](https://cloud.axme.ai/alpha/cli)
+[![License](https://img.shields.io/badge/license-see%20LICENSE-blue)](LICENSE)
+
+[Quick Start](https://cloud.axme.ai/alpha/cli) · [axme](https://github.com/AxmeAI/axme) · [Spec](https://github.com/AxmeAI/axp-spec) · [Examples](https://github.com/AxmeAI/axme-examples)
 
 ---
 
-## What Is AXME?
+## Integration Quickstart
 
-AXME is a coordination infrastructure for durable execution of long-running intents across distributed systems.
+1. **Install the CLI and run your first example**: https://cloud.axme.ai/alpha/cli
+2. Choose your SDK: [Python](https://github.com/AxmeAI/axme-sdk-python) · [TypeScript](https://github.com/AxmeAI/axme-sdk-typescript) · [Go](https://github.com/AxmeAI/axme-sdk-go) · [Java](https://github.com/AxmeAI/axme-sdk-java) · [.NET](https://github.com/AxmeAI/axme-sdk-dotnet)
+3. Follow `docs/integration-quickstart.md` for the full onboarding path
+4. Example hubs:
+   - Cloud runnable: [axme-examples/examples](https://github.com/AxmeAI/axme-examples/tree/main/examples)
+   - Protocol-only: [axme-examples/protocol](https://github.com/AxmeAI/axme-examples/tree/main/protocol)
 
-It provides a model for executing **intents** - requests that may take minutes, hours, or longer to complete - across services, agents, and human participants.
+---
 
-## AXP - the Intent Protocol
+## Key Documents
 
-At the core of AXME is **AXP (Intent Protocol)** - an open protocol that defines contracts and lifecycle rules for intent processing.
+| Document | Description |
+|---|---|
+| [`integration-quickstart.md`](docs/integration-quickstart.md) | End-to-end onboarding path for new integrators |
+| [`public-api-auth.md`](docs/public-api-auth.md) | Authentication: platform API keys, actor tokens, JWT validation |
+| [`security-overview.md`](docs/security-overview.md) | Security architecture, controls, and enterprise review baseline |
+| [`supported-limits-and-error-model.md`](docs/supported-limits-and-error-model.md) | Rate limits, quotas, error codes, retriability table |
+| [`migration-and-deprecation-policy.md`](docs/migration-and-deprecation-policy.md) | API versioning, deprecation timelines, migration guides |
+| [`mcp-api-reference.md`](docs/mcp-api-reference.md) | MCP Server - all 48 tools, auth model, response format |
+| [`cross-org-receive-policy.md`](docs/cross-org-receive-policy.md) | Cross-org intent delivery: org policy + agent overrides |
+| [`agent-addressing.md`](docs/agent-addressing.md) | Agent address registry, agent:// URI scheme |
 
-AXP can be implemented independently.  
-The open part of the platform includes:
+### API Family References
 
-- the protocol specification and schemas
-- SDKs and CLI for integration
-- conformance tests
-- implementation and integration documentation
+| Document | Scope |
+|---|---|
+| [`D1 - Intents, Inbox, Approvals`](docs/public-api-families-d1-intents-inbox-approvals.md) | Intent CRUD, SSE, lifecycle events, human tasks |
+| [`D2 - Webhooks, Capabilities`](docs/public-api-families-d2-webhooks-capabilities.md) | Webhook subscriptions, deliveries, event types |
+| [`D3 - Users`](docs/public-api-families-d3-users.md) | User profiles, nicks, contacts |
+| [`D4 - Invites, Media`](docs/public-api-families-d4-invites-media.md) | Invite links, media upload/download |
+| [`D5 - Schemas`](docs/public-api-families-d5-schemas.md) | Schema governance, payload validation |
+| [`D6 - Enterprise Governance`](docs/public-api-families-d6-enterprise-governance.md) | Orgs, workspaces, members, agents, policies, quotas |
 
-Without AXME Cloud runtime, these open components are still usable for protocol-compatible implementations and validation.
+---
 
-## AXME Cloud
+## Platform Overview
 
-**AXME Cloud** is the managed service that runs AXP in production together with **The Registry** (identity and routing).
+The diagram below shows how AXME components relate: the public gateway, control plane services, connectors, and client SDKs.
 
-It removes operational complexity by providing:
+![AXME System Context - C4 Level 1](docs/diagrams/platform/01-system-context-c4.svg)
 
-- reliable intent delivery and retries  
-- lifecycle management for long-running operations  
-- handling of timeouts, waits, reminders, and escalation  
-- observability of intent status and execution history  
+*The gateway is the single public entry point. Intents flow from SDK clients through TLS to the gateway, which routes them into the durable scheduler and connector layer. Webhooks and MCP callbacks leave the platform from the connector side, cryptographically signed.*
 
-State and events can be accessed through:
+---
 
-- API and SDKs  
-- event streams and webhooks  
-- the cloud console
+## Related Repositories
+
+| Repository | Role |
+|---|---|
+| [axp-spec](https://github.com/AxmeAI/axp-spec) | Canonical schema and protocol contracts |
+| Control-plane runtime (private) | Internal runtime implementation |
+| [axme-conformance](https://github.com/AxmeAI/axme-conformance) | Conformance and contract test suite |
+| [axme-sdk-python](https://github.com/AxmeAI/axme-sdk-python) | Python SDK |
+| [axme-sdk-typescript](https://github.com/AxmeAI/axme-sdk-typescript) | TypeScript SDK |
+| [axme-sdk-go](https://github.com/AxmeAI/axme-sdk-go) | Go SDK |
+| [axme-sdk-java](https://github.com/AxmeAI/axme-sdk-java) | Java SDK |
+| [axme-sdk-dotnet](https://github.com/AxmeAI/axme-sdk-dotnet) | .NET SDK |
+| [axme-cli](https://github.com/AxmeAI/axme-cli) | Command-line interface |
 
 ---
 
@@ -93,105 +119,6 @@ axme-docs/
 
 </details>
 
----
-
-## Platform Overview
-
-The diagram below shows how AXME components relate: the public gateway, control plane services, connectors, and client SDKs.
-
-![AXME System Context - C4 Level 1](docs/diagrams/platform/01-system-context-c4.svg)
-
-*The gateway is the single public entry point. Intents flow from SDK clients through TLS to the gateway, which routes them into the durable scheduler and connector layer. Webhooks and MCP callbacks leave the platform from the connector side, cryptographically signed.*
-
----
-
-## Intent Lifecycle
-
-Every intent progresses through a well-defined state machine. The diagram below shows all states, transitions, and terminal outcomes.
-
-![Intent Lifecycle State Machine](docs/diagrams/intents/01-intent-lifecycle-state-machine.svg)
-
-*Key states: `PENDING → PROCESSING → WAITING_* → DELIVERED → RESOLVED`. Any intent can be cancelled or expire at most transition points. Retry loops are bounded by the policy envelope.*
-
-The complete runtime container view - services, databases, queues, and their connections:
-
-![Container Runtime - C4 Level 2](docs/diagrams/platform/02-container-runtime-c4.svg)
-
-*Gateway (public REST API), agent-core (workflow engine), auth service, MCP platform (48 JSON-RPC tools), and tool registry run as Cloud Run services sharing a PostgreSQL instance. The scheduler runs on the gateway via internal tick endpoints.*
-
----
-
-## Integration Quickstart
-
-1. **Install the CLI and run your first example**: https://cloud.axme.ai/alpha/cli
-2. Choose your SDK: [Python](https://github.com/AxmeAI/axme-sdk-python) · [TypeScript](https://github.com/AxmeAI/axme-sdk-typescript) · [Go](https://github.com/AxmeAI/axme-sdk-go) · [Java](https://github.com/AxmeAI/axme-sdk-java) · [.NET](https://github.com/AxmeAI/axme-sdk-dotnet)
-3. Follow `docs/integration-quickstart.md` for the full onboarding path
-4. Example hubs:
-   - Cloud runnable: [axme-examples/examples](https://github.com/AxmeAI/axme-examples/tree/main/examples)
-   - Protocol-only: [axme-examples/protocol](https://github.com/AxmeAI/axme-examples/tree/main/protocol)
-
----
-
-## Key Documents
-
-| Document | Description |
-|---|---|
-| [`integration-quickstart.md`](docs/integration-quickstart.md) | End-to-end onboarding path for new integrators |
-| [`public-api-auth.md`](docs/public-api-auth.md) | Authentication: platform API keys, actor tokens, JWT validation |
-| [`security-overview.md`](docs/security-overview.md) | Security architecture, controls, and enterprise review baseline |
-| [`supported-limits-and-error-model.md`](docs/supported-limits-and-error-model.md) | Rate limits, quotas, error codes, retriability table |
-| [`migration-and-deprecation-policy.md`](docs/migration-and-deprecation-policy.md) | API versioning, deprecation timelines, migration guides |
-| [`mcp-api-reference.md`](docs/mcp-api-reference.md) | MCP Server - all 48 tools, auth model, response format |
-| [`cross-org-receive-policy.md`](docs/cross-org-receive-policy.md) | Cross-org intent delivery: org policy + agent overrides |
-| [`agent-addressing.md`](docs/agent-addressing.md) | Agent address registry, agent:// URI scheme |
-
-### API Family References
-
-| Document | Scope |
-|---|---|
-| [`D1 - Intents, Inbox, Approvals`](docs/public-api-families-d1-intents-inbox-approvals.md) | Intent CRUD, SSE, lifecycle events, human tasks |
-| [`D2 - Webhooks, Capabilities`](docs/public-api-families-d2-webhooks-capabilities.md) | Webhook subscriptions, deliveries, event types |
-| [`D3 - Users`](docs/public-api-families-d3-users.md) | User profiles, nicks, contacts |
-| [`D4 - Invites, Media`](docs/public-api-families-d4-invites-media.md) | Invite links, media upload/download |
-| [`D5 - Schemas`](docs/public-api-families-d5-schemas.md) | Schema governance, payload validation |
-| [`D6 - Enterprise Governance`](docs/public-api-families-d6-enterprise-governance.md) | Orgs, workspaces, members, agents, policies, quotas |
-
----
-
-## Protocol
-
-AXP wraps every intent in a signed envelope. The protocol layer ensures integrity, ordering, and schema version negotiation.
-
-![AXP Protocol Envelope](docs/diagrams/protocol/01-protocol-envelope.svg)
-
-*The envelope carries the intent payload, sender identity, schema version, idempotency key, and a gateway-applied HMAC signature. Recipients verify the signature before processing.*
-
-Idempotency and replay protection are first-class protocol features:
-
-![Idempotency and Replay Protection](docs/diagrams/protocol/03-idempotency-and-replay-protection.svg)
-
-*Duplicate requests bearing the same idempotency key return the cached response without re-executing. Replay attacks are rejected by the nonce registry.*
-
----
-
-## Security Model
-
-The platform enforces layered security boundaries. The trust boundary diagram maps each enforcement point:
-
-![Security Trust Boundary - DFD](docs/diagrams/security/03-trust-boundary-dfd.svg)
-
-*Public-facing TLS terminates at the gateway. Internal service calls use mTLS. Data at rest is encrypted with AES-256-GCM. Webhook payloads carry HMAC-SHA256 signatures.*
-
-Security control baseline for enterprise review: [`docs/security-overview.md`](docs/security-overview.md).
-
-Authentication and authorization enforcement flow:
-
-![Auth/Authz Enforcement](docs/diagrams/security/01-authn-authz-enforcement-flow.svg)
-
-*API key verification → JWT validation → org/workspace scope check → role-based access → resource-level policy grant evaluation. All steps are audited.*
-
----
-
 <details>
 <summary>Visualization program</summary>
 
@@ -205,31 +132,12 @@ The `docs/diagrams/` directory is the canonical home for all platform visualizat
 
 ---
 
-## Related Repositories
+## Contributing
 
-| Repository | Role |
-|---|---|
-| [axme-spec](https://github.com/AxmeAI/axme-spec) | Canonical schema and protocol contracts |
-| Control-plane runtime (private) | Internal runtime implementation |
-| [axme-conformance](https://github.com/AxmeAI/axme-conformance) | Conformance and contract test suite |
-| [axme-sdk-python](https://github.com/AxmeAI/axme-sdk-python) | Python SDK |
-| [axme-sdk-typescript](https://github.com/AxmeAI/axme-sdk-typescript) | TypeScript SDK |
-| [axme-sdk-go](https://github.com/AxmeAI/axme-sdk-go) | Go SDK |
-| [axme-sdk-java](https://github.com/AxmeAI/axme-sdk-java) | Java SDK |
-| [axme-sdk-dotnet](https://github.com/AxmeAI/axme-sdk-dotnet) | .NET SDK |
-| [axme-cli](https://github.com/AxmeAI/axme-cli) | Command-line interface |
-
----
-
-## Contributing & Contact
-
-- Bug reports and docs feedback: open an issue in this repository
-- Quick Start: https://cloud.axme.ai/alpha/cli - Contact: [hello@axme.ai](mailto:hello@axme.ai)
-- Security disclosures: see [SECURITY.md](SECURITY.md)
-- Contribution guidelines: [CONTRIBUTING.md](CONTRIBUTING.md)
+Bug reports and docs feedback: open an issue in this repository.
 
 <details>
-<summary>Validate this documentation repo locally</summary>
+<summary>Validate locally</summary>
 
 ```bash
 python -m pip install -e ".[dev]"
@@ -238,3 +146,7 @@ pytest
 ```
 
 </details>
+
+---
+
+[hello@axme.ai](mailto:hello@axme.ai) · [@axme_ai](https://x.com/axme_ai) · [Security](SECURITY.md) · [License](LICENSE)

docs/diagrams/DIAGRAM_USAGE_MATRIX.md

@@ -12,13 +12,13 @@ Legend:
 | --- | --- | --- |
 | `intents/01-intent-lifecycle-state-machine.svg` | `axme-control-plane` | `axme-examples` |
 | `intents/02-create-and-control-sequence.svg` | `axme-cli` | `axme-sdk-python` |
-| `intents/03-policy-anatomy.svg` | `axme-control-plane` | `axme-spec` |
+| `intents/03-policy-anatomy.svg` | `axme-control-plane` | `axp-spec` |
 | `intents/04-waiting-branches-and-wakeups.svg` | `axme-control-plane` | `axme-conformance` |
 | `intents/05-delivery-and-processing-pipeline.svg` | `axme-control-plane` | `axme-infra` |
 | `intents/06-internal-scheduler-loop.svg` | `axme-control-plane` | `axme-infra` |
 | `intents/07-access-control-matrix.svg` | `axme-security-ops` | `axme-control-plane` |
 | `intents/08-audit-trail-map.svg` | `axme-conformance` | `axme-security-ops` |
-| `intents/09-intent-payload-extensibility-and-semantic-schemas.svg` | `axme-spec` | `axme-docs` |
+| `intents/09-intent-payload-extensibility-and-semantic-schemas.svg` | `axp-spec` | `axme-docs` |
 | `intents/10-human-in-loop-approval-branches.svg` | `axme-reference-clients` | `axme-mobile` |
 | `intents/11-resume-controls-policy-conflict-resolution.svg` | `axme-conformance` | `axme-reference-clients` |
 
@@ -29,7 +29,7 @@ Legend:
 | `platform/01-system-context-c4.svg` | `axme-docs` | `axme-cloud-landing` |
 | `platform/02-container-runtime-c4.svg` | `axme-control-plane` | `axme-infra` |
 | `platform/03-enterprise-placement-and-boundaries.svg` | `axme-docs` | `axme-reference-clients` |
-| `platform/04-conformance-traceability-map.svg` | `axme-conformance` | `axme-spec` |
+| `platform/04-conformance-traceability-map.svg` | `axme-conformance` | `axp-spec` |
 
 ## API
 
@@ -38,16 +38,16 @@ Legend:
 | `api/01-api-method-family-map.svg` | `axme-sdk-typescript` | `axme-sdk-python` |
 | `api/02-error-model-retriability.svg` | `axme-sdk-go` | `axme-sdk-dotnet` |
 | `api/03-pagination-filtering-sorting-patterns.svg` | `axme-sdk-java` | `axme-sdk-dotnet` |
-| `api/04-rate-limit-and-quota-model.svg` | `axme-cli` | `axme-spec` |
+| `api/04-rate-limit-and-quota-model.svg` | `axme-cli` | `axp-spec` |
 
 ## Protocol
 
 | diagram | primary_repo | secondary_repo |
 | --- | --- | --- |
-| `protocol/01-protocol-envelope.svg` | `axme-spec` | `axme-sdk-typescript` |
-| `protocol/02-versioning-and-deprecation-flow.svg` | `axme-spec` | `axme-docs` |
+| `protocol/01-protocol-envelope.svg` | `axp-spec` | `axme-sdk-typescript` |
+| `protocol/02-versioning-and-deprecation-flow.svg` | `axp-spec` | `axme-docs` |
 | `protocol/03-idempotency-and-replay-protection.svg` | `axme-sdk-python` | `axme-sdk-typescript` |
-| `protocol/04-schema-governance-compatibility.svg` | `axme-spec` | `axme-conformance` |
+| `protocol/04-schema-governance-compatibility.svg` | `axp-spec` | `axme-conformance` |
 | `protocol/05-transport-selection-and-fallbacks.svg` | `axme-examples` | `axme-docs` |
 
 ## Security
@@ -58,7 +58,7 @@ Legend:
 | `security/02-crypto-key-lifecycle.svg` | `axme-security-ops` | `axme-infra` |
 | `security/03-trust-boundary-dfd.svg` | `axme-security-ops` | `axme-docs` |
 | `security/04-secrets-management-rotation-flow.svg` | `axme-security-ops` | `axme-infra` |
-| `security/05-webhook-signature-verification.svg` | `axme-control-plane` | `axme-spec` |
+| `security/05-webhook-signature-verification.svg` | `axme-control-plane` | `axp-spec` |
 | `security/06-threat-model-stride-map.svg` | `axme-local-internal` | `axme-security-ops` |
 | `security/07-data-classification-and-encryption-zones.svg` | `axme-security-ops` | `axme-docs` |
 

docs/diagrams/REPO_DISTRIBUTION_PLAN.md

@@ -12,7 +12,7 @@ Reference matrix:
 
 - `axme-docs`
   - canonical source and catalog for all diagram packs.
-- `axme-spec`
+- `axp-spec`
   - protocol and API diagrams (envelope/versioning/idempotency/error/compatibility).
 
 ### Runtime and reliability

docs/diagrams/platform/04-conformance-traceability-map.dot

@@ -3,7 +3,7 @@ digraph conformance {
     node [shape=box style=filled fillcolor="#dbeafe" fontname="Helvetica" fontsize=11];
     edge [fontname="Helvetica" fontsize=10];
 
-    SPEC  [label="axme-spec\n(schemas + OpenAPI)" fillcolor="#1e40af" fontcolor=white];
+    SPEC  [label="axp-spec\n(schemas + OpenAPI)" fillcolor="#1e40af" fontcolor=white];
     SDK   [label="axme-sdk-*\n(SDK tests)"];
     CONF  [label="axme-conformance\n(conformance suite)"];
     CP    [label="axme-control-plane\n(runtime)"];

docs/diagrams/platform/04-conformance-traceability-map.mmd

@@ -1,5 +1,5 @@
 flowchart LR
-    SPEC[axme-spec\nschemas + OpenAPI]
+    SPEC[axp-spec\nschemas + OpenAPI]
 
     SPEC --> SDK[axme-sdk-*\nSDK tests]
     SPEC --> CONF[axme-conformance\nconformance suite]

docs/enterprise-runtime-model-and-placement.md

@@ -135,9 +135,17 @@ Temporary compatibility behavior:
 5. Confirm intent routing details, usage ledger records, and admin audit events include tenant scope.
 6. Promote to production after staging verification is green.
 
+## Container Runtime View
+
+The complete runtime container view - services, databases, queues, and their connections:
+
+![Container Runtime - C4 Level 2](diagrams/platform/02-container-runtime-c4.svg)
+
+Gateway (public REST API), agent-core (workflow engine), auth service, MCP platform (48 JSON-RPC tools), and tool registry run as Cloud Run services sharing a PostgreSQL instance. The scheduler runs on the gateway via internal tick endpoints.
+
 ## References
 
 - `docs/public-api-families-d6-enterprise-governance.md`
 - `docs/enterprise-scoped-credentials-migration-note.md`
 - `docs/openapi/gateway.track-f-sprint1.v1.json`
-- `axme-spec/schemas/public_api/`
+- `axp-spec/schemas/public_api/`

docs/examples-cloud-vs-protocol.md

@@ -9,7 +9,7 @@ AXME follows an **open protocol + managed runtime** model.
 
 You can still use:
 
-- AXP protocol spec (`axme-spec`)
+- AXP protocol spec (`axp-spec`)
 - SDKs as protocol/client helpers
 - CLI for contract-level checks and endpoint testing
 - conformance suite (`axme-conformance`) for compatibility validation

docs/external-integrator-dry-run.md

@@ -6,10 +6,10 @@ Provide a repeatable public-only verification that a third-party integrator can
 
 ## Required Public Inputs
 
-- `axme-spec/docs/public-api-schema-index.md`
-- `axme-spec/docs/schema-versioning-rules.md`
-- `axme-spec/docs/protocol-error-status-model.md`
-- `axme-spec/docs/idempotency-correlation-rules.md`
+- `axp-spec/docs/public-api-schema-index.md`
+- `axp-spec/docs/schema-versioning-rules.md`
+- `axp-spec/docs/protocol-error-status-model.md`
+- `axp-spec/docs/idempotency-correlation-rules.md`
 - `axme-docs/docs/public-api-auth.md`
 - `axme-docs/docs/supported-limits-and-error-model.md`
 - `axme-docs/docs/migration-and-deprecation-policy.md`
@@ -44,7 +44,7 @@ Provide a repeatable public-only verification that a third-party integrator can
 
 For each dry-run execution, capture:
 
-- date and commit SHAs of `axme-spec` and `axme-docs`,
+- date and commit SHAs of `axp-spec` and `axme-docs`,
 - implemented endpoints and payload contracts,
 - validation result summary,
 - observed issues/gaps and linked follow-up items (if any).