Reading map¶
Which page to read, in what order. For the audience entry points, start at the home page.
Foundation¶
Read these in order before any topic page. Each one assumes the pages above it.
| # | Page | Answers |
|---|---|---|
| 1 | Architecture overview | What the three layers (runtime, connectors, bindings) are, and how a request moves through them |
| 2 | Domain | What connector, action, manifest, ConnectorResponse, ErrorCategory, tenant pin and named config mean |
| 3 | Seams | Where the layers hand off: ConnectorFactory, invoke.py, PolicyHook, SecretProvider, AuthProvider, ErrorMapper |
| 4 | The run() pipeline |
What happens to every action: pin check → validation → policy → resilience → execute → error mapping |
Topic branches¶
Pick the branch you need. "Read first" names the pages it assumes, in addition to the foundation.
| Topic | Page | Answers | Read first |
|---|---|---|---|
| Tenancy | Tenancy | Tenant resolution, entitlement by config, tenant secrets, MCP tenant tools | — |
| Bindings | Connectors on REST, MCP and gRPC | How actions become routes, tools and methods; the manifest; status mapping | — |
| Use | Use a connector | Calling a shipped connector in-process or over REST, per tenant | Tenancy |
| Use | Connector reference | Factory API, connectors.yaml keys, the catalog of shipped connectors |
Use a connector |
| Auth | Build a connector — Authentication | Auth provider types and their connectors.yaml fields |
Seams |
| Build | Build a connector | Writing a connector by hand | Seams |
| Codegen | CLI overview → nw CLI | Generating a connector, wheels and an MCP host from an OpenAPI spec | Build a connector (skim) |
| Codegen | Generator contract | What the OpenAPI generator supports and deliberately does not | nw-connector-builder |
| MCP | MCP overview | Which of the three MCP deployment paths to use; transports; tool search | Bindings |
| MCP | stacklok MCP servers | nw gen-stacklok servers behind ToolHive |
MCP overview, Tenancy |
| MCP | ToolHive agent scenario | Running an agent end to end against ToolHive | MCP overview |
| Ship | Packaging | Wheels, the new-connector ship checklist, PyPI release | Build a connector |
| Ship | Local wheels → images | Building and composing the per-connector MCP images | Packaging |
Operator tasks¶
Task pages you can open directly: Installation · Configuration · Troubleshooting · Release & rollback · Versioning · Privacy · HIPAA considerations.
Why things are the way they are¶
Decisions are frozen records, separate from the pages above: Architecture decision records.
Who owns what¶
One fact, one owning page. Other pages link here instead of restating it.
| Fact | Owner |
|---|---|
| Quick start | Home |
| Prerequisites, dependency install, optional telemetry stack | Installation |
Every NW_* variable and its default |
Configuration |
| The three layers | Architecture |
| Tenant resolution, entitlement, tenant secrets, MCP tenant tools | Tenancy |
| Auth provider types and fields | Build a connector — Authentication |
| Scope policy for callers | Build a connector — Security |
| Per-connector actions, auth and secrets | Connector reference — catalog |
| Ship checklist for a new connector (runtime, PyPI, MCP image) | Packaging |
| Building and composing MCP images | Local wheels → images |
| MCP deployment paths | MCP overview |
| Which CLI command to run | CLI overview |
| What the OpenAPI generator supports | Generator contract |
| Local quality commands | Code quality |
| CI gates and branch protection | Quality & security gates |
| Error codes, categories and what each surface returns | Errors, checked by tests/test_docs_lifecycle.py |
| Stable public API | Public API, checked by tests/test_docs_lifecycle.py |
Changing the docs¶
The rules are recorded in ADR 0002. When a change touches documented behaviour:
- Find the owning page in the table above. If the fact has no owner yet, pick one and add a row.
- Check the claim against the code, not against another page.
- Edit the owning page in place. If you find a copy elsewhere, delete it and link to the owner.
- Keep bug chronology, repair notes and "fixed along the way" lists in the PR and
CHANGELOG.md. Living pages say what is true now. They carry noStatus:line. - A new decision is a new ADR. Never rewrite an accepted one.
- When you move a page, leave a short redirect stub at the old path, outside the navigation.
mkdocs build --strict fails on broken links. uv run pytest tests/test_docs_lifecycle.py fails
when a living page carries a Status: line, when an ADR is in the wrong part of the navigation, or
when the public API or package inventory no longer matches the code.