Repo structure to host proposals, apis

README.md

@@ -34,6 +34,10 @@ This subproject aims to deliver the following:
 
 You can find a quick start guide [here](https://kube-agentic-networking.sigs.k8s.io/guides/quickstart/).
 
+## Repository structure
+
+See [docs/design/repo_structure.md](docs/design/repo_structure.md) for where to find and add proposals, APIs, documentation, and code.
+
 ## Community, discussion, contribution, and support
 
 Our community meetings are held weekly on Thursday at 8:00 AM PT (Pacific Time) ([Convert to your timezone](http://www.thetimezoneconverter.com/?t=08%3A00&tz=PT%20%28Pacific%20Time%29)).

docs/design/api.md

@@ -0,0 +1,38 @@
+# API design
+
+This document describes the design of the project’s custom APIs and how they fit with the Gateway API.
+
+## Overview
+
+The project extends the [Kubernetes Gateway API](https://gateway-api.sigs.k8s.io/) with two main custom resources:
+
+- **XBackend** — describes a backend (e.g. an MCP server) that HTTPRoutes can reference via BackendRef.
+- **XAccessPolicy** — describes who can access what: it targets one or more XBackends and defines rules (sources and authorization) that the data plane enforces.
+
+Type definitions and generated code live under [`api/`](../../api/) and [`k8s/`](../../k8s/). For a short “what lives where” guide, see [repo_structure.md](repo_structure.md).
+
+## XBackend
+
+An **XBackend** represents a backend that agents or tools call into—for example, an MCP server. It is namespaced and is referenced by HTTPRoute `BackendRef`s (and by XAccessPolicy targetRefs). The controller and translator use XBackends to configure the data plane (e.g. clusters, RBAC) so that traffic to that backend is correctly routed and authorized.
+
+Key design points:
+
+- One XBackend per logical backend (e.g. one MCP server).
+- Backend identity can be specified by Kubernetes Service name (in-cluster) or by hostname (external).
+- The data plane uses XBackend to know where to send traffic and how to secure it (e.g. mTLS, path).
+
+## XAccessPolicy
+
+An **XAccessPolicy** is an authorization policy: it defines *who* can access *what* for the backends it targets. It targets XBackends via `targetRefs` and contains rules that describe allowed (or denied) sources and optional authorization (e.g. which tools or methods). The translator turns XAccessPolicy into data-plane configuration (e.g. Envoy RBAC) so that only allowed callers can reach the targeted backends.
+
+Key design points:
+
+- Targets one or more XBackends via `targetRefs`.
+- Rules combine a source (e.g. service account, namespace) with optional authorization (e.g. allowed tools/methods).
+- If no XAccessPolicy targets an XBackend, the data plane does not enforce RBAC for that backend (allow-all behaviour). If at least one XAccessPolicy targets it, the translated rules are enforced.
+
+## Relationship to Gateway API
+
+The project is built on top of the Gateway API and works with Gateway resources (Gateway, GatewayClass, and route types such as HTTPRoute; GRPCRoute may be supported later). Route resources can reference XBackends via BackendRef. **XBackend** and **XAccessPolicy** are custom resources that work with these Gateway resources and the data plane: BackendRef → XBackend, and XAccessPolicy → RBAC (or equivalent) for those backends.
+
+Proposals that introduce or change these APIs are under [docs/proposals/](../proposals/).

docs/design/repo_structure.md

@@ -0,0 +1,60 @@
+# Repository structure
+
+This document describes where to find and where to add proposals, APIs, documentation, and code in this repo.
+
+## Top-level layout
+
+```
+├── api/                 # API type definitions (Go structs)
+├── cmd/                 # Application entrypoints (e.g. controller main)
+├── docs/                # Design docs, proposals, and repo documentation
+├── hack/                # Build, codegen, and CI helpers
+├── k8s/                 # Generated clients, CRDs, and deploy manifests
+├── pkg/                 # Go packages (controller, translator, infra, etc.)
+├── quickstart/          # Quickstart examples (agents, MCP server, policy)
+├── site-src/            # MkDocs source for the published docs site
+└── tests/               # Tests (CEL, CRD validation, examples)
+```
+
+## Proposals
+
+**Location:** [`docs/proposals/`](../proposals/)
+
+Design proposals and enhancement docs live here. Each proposal is a markdown file.
+
+- **Naming:** `NNNN-short-title.md` (e.g. `0008-ToolAuthAPI.md`). Use the 4-digit PR number once the PR exists; use a placeholder like `XXXX-my-proposal` during development.
+- **Index and practices:** See [docs/design/proposals.md](proposals.md).
+
+## APIs
+
+**Type definitions:** [`api/`](../../api/) (Go)
+
+- `api/v0alpha0/` — Current API version (e.g. `backend_types.go`, `accesspolicy_types.go`). Run `make generate` after editing.
+
+**CRDs (manifests):** [`k8s/crds/`](../../k8s/crds/)
+
+- Installed YAML for XBackend, XAccessPolicy, etc. Generated from `api/`.
+
+**Generated clients:** [`k8s/client/`](../../k8s/client/)
+
+- Clientsets, listers, informers for the API types. Regenerated via project Makefile/codegen.
+
+For an overview of the APIs and design, see [api.md](api.md).
+
+## Documentation
+
+- **Design docs (this folder):** [`docs/design/`](.) — API design, repo structure, control plane, data plane.
+- **Repo docs (proposals, api):** [`docs/`](../) — Markdown in the repo; good for GitHub browsing and linking from the docs site.
+- **Published docs site:** [`site-src/`](../../site-src/) — MkDocs source; built output goes to `site/`. Add user-facing pages, guides, and links to proposals/APIs here. Config: [`mkdocs.yml`](../../mkdocs.yml).
+
+## Code
+
+- **Controller and business logic:** [`pkg/controller/`](../../pkg/controller/), [`pkg/translator/`](../../pkg/translator/)
+- **Infrastructure (xDS, Envoy, pod certificate signer):** [`pkg/infra/`](../../pkg/infra/)
+- **Constants and shared config:** [`pkg/constants/`](../../pkg/constants/)
+- **Entrypoint:** [`cmd/`](../../cmd/)
+
+## Quickstart and examples
+
+- **Quickstart:** [`quickstart/`](../../quickstart/) — ADK agent, MCP server, and policy examples (e.g. `quickstart/policy/e2e.yaml`).
+- **CRD examples (valid/invalid):** [`tests/crd/examples/`](../../tests/crd/examples/)

docs/proposals/README.md

@@ -1,5 +1,24 @@
-# Proposals Best Practices
+# Proposals
 
+Design proposals and enhancement documents for Kubernetes Agentic Networking.
+
+## Index
+
+| Proposal | Description |
+|----------|-------------|
+| [0008-ToolAuthAPI.md](0008-ToolAuthAPI.md) | Tool Authorization API |
+| [0017-DynamicAuth.md](0017-DynamicAuth.md) | Dynamic Auth |
+| [0059-AccessPolicyTargetRefs.md](0059-AccessPolicyTargetRefs.md) | AccessPolicy TargetRefs |
 
 ## Naming
-The directory of the proposal should lead with a 4-digit PR number (will move to 5,6,... should our PR count get that high), followed by kebab-cased title. The PR number is not known until the PR is cut, so development can use a placeholder, ex. XXXX-my-proposal. PR number is used b/c it is unique & chronological, allowing the default ordering of proposals to follow the timeline of development.
+
+- Use a **4-digit number** (PR number when available) followed by a **kebab-cased title**: `NNNN-short-title.md`.
+- Examples: `0008-ToolAuthAPI.md`, `0059-AccessPolicyTargetRefs.md`.
+- While developing, you can use a placeholder (e.g. `XXXX-my-proposal.md`) and rename to the PR number when the PR is opened.
+- The number gives a chronological order to proposals.
+
+## Adding a new proposal
+
+1. Create a new markdown file under `docs/proposals/` with the naming above.
+2. Include: context, goals, design (API changes, behavior), and alternatives considered.
+3. Add the new proposal to the **Index** table in this README.