agntcy · keraron · May 21, 2026 · May 21, 2026 · May 21, 2026
@@ -1,6 +1,6 @@
 # Continuous System Integration Testing
 
-The Agncty Continuous System Integration Testing (CSIT) system design needs to meet the continuously expanding requirements of Agntcy projects, such as the [Agent Directory Service](../dir/overview.md).
+The Agncty Continuous System Integration Testing (CSIT) system design needs to meet the continuously expanding requirements of Agntcy projects, such as the [Agent Directory Service](../dir/dir-overview.md).
 
 Tests can be run locally using taskfile or in GitHub Actions.
 

@@ -1,25 +1,32 @@
 nav:
-  - Overview: overview.md
-  - Getting Started:
-    - dir-getting-started.md
+  - Get Started:
+    - Overview: dir-overview.md
+    - Features and Usage Scenarios: dir-features-scenarios.md
+    - Quickstart: dir-quickstart.md
+  - Concepts:
+    - Architecture: dir-architecture.md
+    - Records: dir-component-records-validation.md
+    - Store: dir-component-store.md
+    - Routing: dir-component-routing.md
+    - Trust Model: dir-component-trust-model.md
+    - Federation: dir-federation-overview.md
+    - Extensions:
+      - Runtime Discovery: dir-component-runtime-discovery.md
+      - Event Streaming: dir-component-event-streaming.md
+      - MCP Server: dir-component-mcp-server.md
+      - GUI: dir-component-gui.md
+  - Deploy:
     - Local Deployment: dir-deployment-local.md
     - Kubernetes Deployment: dir-deployment-kubernetes.md
-  - OIDC Authentication: directory-oidc-authentication.md
-  - Features and Usage Scenarios: scenarios.md
-  - Production Deployment: prod-deployment.md
-  - CLI Guide: directory-cli.md
-  - MCP Server: directory-mcp.md
-  - Federation:
-    - Federation on Amazon EKS: federation-aws-eks.md
-    - Running a Federated Directory Instance: partner-prod-federation.md
-    - Profiles: federation-profiles.md
-    - Best Practices and Troubleshooting: federation-troubleshooting.md
+    - Production Deployment: dir-prod-deployment.md
+    - Federation Deployment:
+      - Federation on Amazon EKS: dir-federation-aws-eks.md
+      - Running a Federated Directory Instance: dir-federation-setup.md
+      - Profiles: dir-federation-profiles.md
+      - Best Practices and Troubleshooting: dir-federation-troubleshooting.md
+    - OIDC Authentication: dir-component-oidc-authentication.md
+  - SDKs:
+    - SDK Overview: dir-sdk.md
   - Reference:
-    - CLI Reference: directory-cli-reference.md
+    - CLI Reference: dir-cli-reference.md
     - API Reference: dir-api-reference.md
-  - Architecture: architecture.md
-  - Components:
-    - Runtime Discovery: runtime.md
-    - Event Streaming: events.md
-    - Records and Validation: records-validation.md
-  - Trust Model: trust-model.md
@@ -1,3 +1,28 @@
-# Directory API Reference
+# API Reference
 
-The Directory API reference is available at [buf.build/agntcy/dir](https://buf.build/agntcy/dir).
+Directory exposes a **gRPC** API defined with Protocol Buffers. Generated clients and the
+canonical schema live on [buf.build/agntcy/dir](https://buf.build/agntcy/dir).
+
+## Protocol surface
+
+| Area | Description |
+|------|-------------|
+| **Storage** | Push, pull, and manage OASF records in the OCI-backed store |
+| **Routing** | Publish skill announcements, list local records, search the network |
+| **Search** | Structured queries over the local index |
+| **Security** | Signing, verification, naming, and validation |
+| **Sync** | Peer synchronization between directory instances |
+| **Events** | Streaming directory events ([Events API](https://buf.build/agntcy/dir/docs/main:agntcy.dir.events.v1)) |
+| **Runtime** | Runtime discovery for containerized workloads |
+
+Use the Buf schema browser for message types, RPC names, and versioned packages. The
+[Architecture](dir-architecture.md) page describes how these APIs map to Directory components.
+
+## Clients
+
+- **CLI** — [Directory CLI Reference](dir-cli-reference.md) (`dirctl`)
+- **SDKs** — [Go, Python, and JavaScript](dir-sdk.md) libraries
+- **MCP** — [MCP Server](dir-component-mcp-server.md) for tool-based access
+
+For HTTP/gateway access patterns and OIDC, see
+[OIDC Authentication](dir-component-oidc-authentication.md).
@@ -2,6 +2,10 @@
 
 The architecture of the Agent Directory Service (ADS) is designed to support a scalable, secure, and efficient way to manage and distribute agent directory records across a distributed network of servers.
 
+Directory’s gRPC APIs and protobuf schemas are published on
+[buf.build/agntcy/dir](https://buf.build/agntcy/dir). See the [API Reference](dir-api-reference.md)
+for an overview of the protocol surface.
+
 ## Components
 
 - **Records**: The fundamental units of information in the ADS, representing individual agents and their capabilities. Each record is uniquely identified and contains metadata describing the agent's skills, attributes, and constraints.
@@ -20,6 +24,19 @@ The architecture of the Agent Directory Service (ADS) is designed to support a s
 
 - **Security and Trust Mechanisms**: Features that ensure the integrity and authenticity of directory records and nodes, including cryptographic signing, verification of claims, secure communication protocols, and access controls.
 
+### Core vs extensions
+
+Per the [Directory specification](https://github.com/agntcy/dir-spec), **Records**, **Store**, and
+**Routing** are the defining core components. They are documented at depth in
+[Records](dir-component-records-validation.md), [Store](dir-component-store.md), and
+[Routing](dir-component-routing.md).
+
+Optional **extensions** include
+[Runtime Discovery](dir-component-runtime-discovery.md),
+[Event Streaming](dir-component-event-streaming.md), the
+[MCP Server](dir-component-mcp-server.md), and the [GUI](dir-component-gui.md). External access
+via [OIDC](dir-component-oidc-authentication.md) is configured at deployment time.
+
 ## Principles
 
 - **Scalability**: The ADS is designed to handle a large number of servers and records, with the ability to scale horizontally by adding more directory servers to the network.

@@ -0,0 +1,7 @@
+# Directory CLI Guide
+
+The CLI guide has been reorganized:
+
+- **Installation and first publish/discover flow** — [Quickstart](dir-quickstart.md)
+- **Workflow examples** (sync, import, export, events) — [Features and Usage Scenarios](dir-features-scenarios.md)
+- **Command reference** — [Directory CLI Reference](dir-cli-reference.md)
@@ -1,5 +1,82 @@
 # Directory CLI Command Reference
 
+Command-line reference for `dirctl`. Install the CLI in the [Quickstart](dir-quickstart.md)
+only; workflow examples live in [Features and Usage Scenarios](dir-features-scenarios.md).
+
+## Global options
+
+### Output formats
+
+All commands support `--output` / `-o`:
+
+| Format | Description | Use case |
+|--------|-------------|----------|
+| `human` | Formatted tables and colors (default) | Interactive use |
+| `json` | Pretty-printed JSON | Debugging, single-record scripts |
+| `jsonl` | One JSON object per line | Streaming, batch processing |
+| `raw` | Values only (CIDs, IDs) | Shell pipelines |
+
+Structured formats send data to **stdout** and messages to **stderr**, so piping to `jq`
+works cleanly.
+
+```bash
+CID=$(dirctl push record.json -o raw)
+dirctl routing search --skill "AI" -o json | jq '.[] | .record_ref.cid'
+dirctl events listen -o jsonl | jq -c 'select(.type == "EVENT_TYPE_RECORD_PUSHED")'
+```
+
+### Server connection
+
+```bash
+dirctl --server-addr localhost:8888 routing list
+export DIRECTORY_CLIENT_SERVER_ADDRESS=localhost:8888
+dirctl --context dev routing list   # see Context Operations below
+```
+
+### Authentication
+
+For remote servers, authenticate with OIDC before running commands. The full auth model,
+gateway endpoints, and SPIFFE/SPIRE integration are documented in
+[OIDC Authentication](dir-component-oidc-authentication.md).
+
+| Command | Description |
+|---------|-------------|
+| `dirctl auth login` | OIDC login (PKCE, `--no-browser`, or `--device`) |
+| `dirctl auth logout` | Clear cached credentials |
+| `dirctl auth status` | Show current auth state |
+
+```bash
+dirctl auth login --oidc-issuer "https://prod.idp.ads.outshift.io" --oidc-client-id "dirctl"
+dirctl --auth-mode=oidc --server-addr prod.gateway.ads.outshift.io:443 search --skill "AI"
+```
+
+Pre-issued tokens: `--auth-token` or `DIRECTORY_CLIENT_AUTH_TOKEN` for CI and automation.
+Other modes: `--auth-mode=x509`, `jwt`, `tls`, or `insecure` for local development. Default
+(empty) auto-detects SPIFFE → OIDC → insecure.
+
+### Command groups
+
+| Group | Commands |
+|-------|----------|
+| Daemon | `daemon start`, `stop`, `status` |
+| Auth | `auth login`, `logout`, `status` |
+| Context | `context list`, `current`, `set`, `show`, `validate` |
+| Storage | `push`, `pull`, `delete`, `info` |
+| Import / Export | `import`, `export` |
+| Routing | `routing publish`, `list`, `search` |
+| Search | `search` |
+| Security | `sign`, `verify`, `validate`, `naming verify` |
+| Sync | `sync create`, `status`, `list`, `delete` |
+| Events | `events listen` |
+
+### Getting help
+
+```bash
+dirctl --help
+dirctl routing --help
+dirctl routing search --help
+```
+
 ## Daemon Operations
 
 The daemon commands run a self-contained local directory server that bundles the gRPC apiserver and reconciler into a single process with embedded SQLite and a filesystem OCI store. All state is stored under `~/.agntcy/dir/` by default.
@@ -935,7 +1012,7 @@ Record name verification proves that the signing key is authorized by the domain
     dirctl sign <cid> --key private.key
     ```
 
-3. Check verification status using [`dirctl naming verify`](./directory-cli.md#dirctl-naming-verify-reference).
+3. Check verification status using [`dirctl naming verify`](#dirctl-naming-verify-reference).
 
 ### `dirctl sign <cid> [flags]`
 

@@ -500,6 +500,6 @@ DIRECTORY_SERVER_EVENTS_LOG_PUBLISHED_EVENTS=false
 ## See Also
 
 - [Events API Reference](https://buf.build/agntcy/dir/docs/main:agntcy.dir.events.v1) - Protocol buffer definitions and message formats
-- [CLI Reference](directory-cli.md) - Complete CLI command documentation
-- [SDK Reference](directory-sdk.md) - Language-specific SDK usage guides
-- [Getting Started](dir-getting-started.md) - Initial setup and deployment guide
+- [CLI Reference](dir-cli-reference.md) — `dirctl events listen` and related commands
+- [SDK Overview](dir-sdk.md) — language-specific SDK usage
+- [Quickstart](dir-quickstart.md) — install CLI and start a local Directory
@@ -105,4 +105,4 @@ Using the Directory MCP Server, you can access the following tools:
 - `agntcy_dir_verify_record` - Verifies the digital signature of a record in the Directory by its CID (server-side integrity and authenticity).
 - `agntcy_dir_verify_name` - Verifies that a record's name is owned by the domain it claims (by CID or name; optional version). Checks that the record was signed with a key published in the domain's well-known JWKS file.
 
-For a full list of tools and usage examples, see the [Directory MCP Server documentation](https://github.com/agntcy/dir/blob/main/mcp/README.md).
+For a full list of tools and usage examples, see the [Directory MCP Server GitHub repository](https://github.com/agntcy/dir-mcp).
@@ -85,7 +85,7 @@ This keeps token handling and policy enforcement at the edge rather than spreadi
 
 Human users typically authenticate with `dirctl auth login`, using browser-based PKCE, headless login, or device flow. This is the best fit for operators and developers who need interactive CLI access to a remote Directory.
 
-Use the [CLI Guide](directory-cli.md#authentication) for command examples and token cache behavior.
+Use the [CLI Reference](dir-cli-reference.md#global-options) for command examples and token cache behavior.
 
 ### Service Users and Non-Interactive Automation
 
@@ -155,7 +155,7 @@ In both cases, the Directory-facing model is the same: the edge validates tokens
 
 The two main operator touchpoints are:
 
-- [`directory-cli.md`](directory-cli.md) for user-facing commands such as `dirctl auth login`, `dirctl auth status`, `--auth-mode=oidc`, and pre-issued token usage
+- [CLI Reference](dir-cli-reference.md#global-options) for `dirctl auth login`, `dirctl auth status`, `--auth-mode=oidc`, and pre-issued token usage
 - deployment configuration for Envoy and the `ext_authz` layer that trusts one or more issuers and maps verified identities to principals and roles
 
 When documenting or configuring this feature, it helps to think in three layers:
@@ -369,7 +369,7 @@ Client identity -> Envoy validation -> `ext_authz` canonical principal mapping -
 
 ## Further Reading
 
-- [CLI Guide](directory-cli.md) for command-level usage
-- [Getting Started](dir-getting-started.md) for deployment entry points
-- [Production Deployment](prod-deployment.md) for production topology and external endpoints
-- [Running a Federated Directory Instance](partner-prod-federation.md) for network federation guidance
+- [CLI Reference](dir-cli-reference.md) for command-level usage
+- [Quickstart](dir-quickstart.md) and [Deploy](dir-deployment-local.md) for deployment entry points
+- [Production Deployment](dir-prod-deployment.md) for production topology and external endpoints
+- [Running a Federated Directory Instance](dir-federation-setup.md) for network federation guidance
@@ -21,7 +21,7 @@ Records must include a `name` field with a domain-based identifier that enables
 - The domain must host a JWKS file at `<scheme>://<domain>/.well-known/jwks.json`.
 - Records signed with a private key associated with a public key present in that JWKS file can be verified as authorized by the domain.
 
-See the [Directory CLI documentation](directory-cli.md#name-verification) for details on name verification workflows.
+See [Features and Usage Scenarios — Name Verification](dir-features-scenarios.md#name-verification) and the [CLI Reference](dir-cli-reference.md#security-verification) for name verification workflows.
 
 ### Example Email Agent
 

@@ -0,0 +1,31 @@
+# Routing
+
+**Routing** (content routing) is a core Directory component that maps agent **skills** to
+record identifiers and to the directory servers that host those records. It builds on a
+[Distributed Hash Table (DHT)](https://en.wikipedia.org/wiki/Distributed_hash_table) so
+discovery scales across a decentralized network of peers.
+
+## Announce and discover
+
+Publishing a record to the network is a two-step process:
+
+1. **Store** — push the record to local storage and obtain its CID.
+2. **Announce** — call `routing publish` so the server advertises the CID and its skill
+   taxonomy in the DHT. Announcements are processed asynchronously and have a TTL; republish
+   periodically to keep routing data fresh.
+
+Discovery uses:
+
+- **`routing list`** — records indexed on the local peer only.
+- **`routing search`** — records announced by remote peers (cached network view).
+
+Skill matching supports exact and hierarchical prefix matching. Network search results
+reflect cached announcements and may be stale or incomplete until peers replicate records.
+
+## Related documentation
+
+- [Architecture](dir-architecture.md) — full system design and diagram
+- [Records](dir-component-records-validation.md) — skill taxonomy and record structure
+- [Features and Usage Scenarios — Announce / Discover](dir-features-scenarios.md#announce) — CLI walkthroughs
+- [CLI Reference — Routing Operations](dir-cli-reference.md#routing-operations) — `routing publish`, `list`, `search`
+- [Federation](dir-federation-overview.md) — multi-instance routing across federated directories
@@ -265,7 +265,7 @@ Discovered workloads have a `services` field that holds metadata extracted by re
 
 The OASF resolver requires Directory client configuration via environment variables.
 These are the same as those used by the Directory client library, e.g. `DIRECTORY_CLIENT_SERVER_ADDRESS`.
-Refer to the [Directory Go SDK](./directory-sdk.md#go-sdk) for all available options.
+Refer to the [Directory Go SDK](./dir-sdk.md#go-sdk) for all available options.
 
 When a workload has the configured OASF resolver label, the resolver attempts to fetch the corresponding record from Directory and validate its signature before attaching it to the workload.
 

@@ -0,0 +1,28 @@
+# Store
+
+The **Store** is a core Directory component that persists agent records as
+[OCI](https://opencontainers.org) artifacts in a registry-backed content store.
+
+## Role in the system
+
+When a client pushes a record, the server:
+
+1. Validates the record against the [OASF](../oasf/open-agentic-schema-framework.md) schema.
+2. Writes the payload to the configured OCI registry.
+3. Derives a [content identifier (CID)](https://github.com/multiformats/cid) from the artifact digest for immutable, content-addressed lookup.
+
+Records can be retrieved by CID or, when configured with a verifiable name, by
+Docker-style name references (`name`, `name:version`, `name:version@cid`).
+
+## Backends
+
+Directory supports OCI-compatible registries including [Zot](https://github.com/project-zot/zot)
+(default for local deployments), GitHub Container Registry, and Docker Hub. The server selects
+the backend via store configuration (see [Local Deployment](dir-deployment-local.md) and
+[Production Deployment](dir-prod-deployment.md)).
+
+## Related documentation
+
+- [Records](dir-component-records-validation.md) — OASF record model, CIDs, and validation
+- [Features and Usage Scenarios — Store](dir-features-scenarios.md#store) — CLI examples and registry configuration
+- [CLI Reference — Storage Operations](dir-cli-reference.md#storage-operations) — `push`, `pull`, `delete`, `info`
@@ -108,7 +108,7 @@ flowchart LR
 - SPIRE Servers exchange bundles to establish federation
 - Enables secure, authenticated communication between workloads in different domains
 
-For step-by-step federation setup with the public Directory network, see [Running a Federated Directory Instance](partner-prod-federation.md). For technical details on federation profiles (https_web vs https_spiffe), see [Federation Profiles](federation-profiles.md).
+For step-by-step federation setup with the public Directory network, see [Running a Federated Directory Instance](dir-federation-setup.md). For technical details on federation profiles (https_web vs https_spiffe), see [Federation Profiles](dir-federation-profiles.md).
 
 ```mermaid
 flowchart TD
@@ -147,11 +147,11 @@ as a standalone service, providing flexibility for different infrastructure setu
 - **Federation Support**: Federation is enabled to allow cross-domain
 trust relationships between different SPIRE deployments.
 If the federation is not required, it can be left disabled.
-See [Running a Federated Directory Instance](partner-prod-federation.md) for configuration.
+See [Running a Federated Directory Instance](dir-federation-setup.md) for configuration.
 
 - **Bundle Endpoint**: Exposes a bundle endpoint that enables federation
 by allowing other SPIRE servers to exchange trust bundles.
-See [Federation Profiles](federation-profiles.md) for profile options (https_web, https_spiffe).
+See [Federation Profiles](dir-federation-profiles.md) for profile options (https_web, https_spiffe).
 
 ```bash
 # Set the trust domain
@@ -285,7 +285,7 @@ task test:spire:cleanup
 
 For more details, see:
 
-- [Running a Federated Directory Instance](partner-prod-federation.md) - Connect to the public Directory network
-- [Federation Profiles](federation-profiles.md) - https_web vs https_spiffe configuration
+- [Running a Federated Directory Instance](dir-federation-setup.md) - Connect to the public Directory network
+- [Federation Profiles](dir-federation-profiles.md) - https_web vs https_spiffe configuration
 - [SPIRE Documentation](https://spiffe.io/docs/latest/spiffe-about/overview/)
 - [SPIRE Federation Guide](https://spiffe.io/docs/latest/spire-helm-charts-hardened-advanced/federation/)