feat(auth0): split large references into hub+leaf groups (reference depth)

AGENTS.md

@@ -8,17 +8,21 @@ An **Agent Skill** that teaches coding assistants how to implement Auth0
 authentication that follows Auth0's documented SDK usage and passes this
 repo's routing and behavioral evals. It ships as a single Claude Code / Cursor / Copilot
 plugin (`auth0`) containing **one** consolidated skill at
-`plugins/auth0/skills/auth0/`: a router `SKILL.md` over a flat pool of on-demand
-reference files. The deliverable is the skill itself.
+`plugins/auth0/skills/auth0/`: a router `SKILL.md` over a pool of on-demand
+reference files, some of which are grouped into hub+leaf directories. The
+deliverable is the skill itself.
 
 ## Repository layout
 
 ```
 plugins/auth0/skills/auth0/
 ├── SKILL.md            # Required: the router (only file allowed in skill root)
-├── references/         # Flat pool of on-demand docs, each reachable from SKILL.md:
-│                       #   framework-<name>.md, feature-<name>.md,
-│                       #   tooling-<name>.md, pattern-<name>.md (kebab-case)
+├── references/         # On-demand docs, each reachable from SKILL.md. Every
+│                       #   reference is a directory — framework-<name>/,
+│                       #   feature-<name>/, tooling-<name>/, pattern-<name>/
+│                       #   (kebab-case) — with an index.md that is either the
+│                       #   whole reference (index-only) or a hub + document-
+│                       #   section leaves (leaf group).
 ├── scripts/            # Optional: executable helpers
 └── assets/             # Optional: static resources (templates, data)
 
@@ -42,12 +46,14 @@ Key top-level docs:
 1. Read [`CONTRIBUTING.md`](./CONTRIBUTING.md). The conventions there are
    enforced and not optional.
 2. Match the patterns of the existing reference files rather than inventing new
-   structure. The flat naming convention (`framework-<name>.md`,
-   `feature-<name>.md`, `tooling-<name>.md`, `pattern-<name>.md`) and the
-   router-in-`SKILL.md` layout exist on purpose — keep them consistent. Every
-   new reference file must be reachable from `SKILL.md` and must not link to
-   another reference file (the one-hop rule, enforced by
-   `scripts/check_router_reachability.py`).
+   structure. The naming convention (`framework-<name>`, `feature-<name>`,
+   `tooling-<name>`, `pattern-<name>`) and the router-in-`SKILL.md` layout
+   exist on purpose — keep them consistent. Navigation is a **depth-2 tree**:
+   every reference must be reachable from `SKILL.md`; an index-only `index.md`
+   or a group leaf must not link to any other `.md`; the only allowed second hop
+   is a leaf-group hub `index.md` dispatching to leaves in its own directory.
+   Enforced by `scripts/check_router_reachability.py`. See CONTRIBUTING.md →
+   "Adding a reference" before splitting a large one into a leaf group.
 
 ## Required SKILL.md frontmatter
 

CONTRIBUTING.md

@@ -140,16 +140,25 @@ All Auth0 guidance ships in the single `auth0` skill
 for why. To add or change coverage:
 
 ### Pick the right reference prefix
-- `feature-<name>.md` — a capability spanning frameworks (e.g. mfa, dpop).
-- `framework-<name>.md` — a single SDK/framework integration.
-- `tooling-<name>.md` — a provisioning tool (cli, mcp, terraform).
-- `pattern-<name>.md` — cross-cutting guidance.
+Every reference is a directory `<name>/` with an `index.md` (see "Adding a
+reference"); pick the prefix that fits:
+- `feature-<name>/` — a capability spanning frameworks (e.g. mfa, dpop).
+- `framework-<name>/` — a single SDK/framework integration.
+- `tooling-<name>/` — a provisioning tool (cli, mcp, terraform).
+- `pattern-<name>/` — cross-cutting guidance.
 
 ### Make it routable (required — CI enforces this)
-Every file in `references/` MUST be reachable from `SKILL.md`, and no reference
-file may contain a link to any `.md` file (reference files are self-contained —
-inline the content instead of linking, since Claude Code follows only one hop
-from the router).
+Every reference in `references/` MUST be reachable from `SKILL.md`. Navigation is
+a **depth-2 tree**: every reference is a directory `<name>/` with an `index.md`.
+An **index-only** reference puts its whole content in `index.md` and has no
+leaves (one hop from the router). A large reference is a **leaf group** whose
+`index.md` is a hub plus document-section leaves (see "Adding a reference" below).
+An index-only `index.md` and any leaf inside a leaf group may contain **no** link
+to any `.md` file — they are sinks; inline the content instead of linking. The
+only second hop allowed is a leaf-group hub `index.md` dispatching to leaves **in
+its own directory**; cross-group links are forbidden. Claude Code follows the
+router to `index.md` (and, for a leaf group, on to one leaf) — nothing deeper is
+guaranteed.
 
 - **New feature:** add an intent row in Step 1 and a load block in Step 4 of
   `SKILL.md`.
@@ -158,12 +167,58 @@ from the router).
   keyword) — and, if it has a web-vs-API split, a row in "Variant
   disambiguation." The reachability checker derives routable slugs directly from
   these router tables (the backticked value column), so simply naming your
-  `<slug>` in a table makes `framework-<slug>.md` reachable — there is no
+  `<slug>` in a table makes `framework-<slug>/index.md` reachable — there is no
   separate list to update.
 
+### Adding a reference
+Every reference is a directory named after its stem, containing an `index.md`.
+Adding a new reference means creating `references/<name>/index.md`. Start
+index-only — the whole reference lives in `index.md` — and only split it into a
+**leaf group** once it grows large (roughly >40K) so the router pulls just the
+slice a task needs instead of the whole file:
+
+```
+references/framework-<name>/
+├── index.md          # hub: shared prerequisites + intent→leaf dispatch table
+├── integrate.md      # document-section leaves (one per section, not per intent)
+├── api-reference.md
+├── patterns.md
+├── setup.md
+└── migration.md      # only if the SDK has a major-version migration
+```
+
+Rules for splitting a large reference into a leaf group:
+- **Leaves are document sections**, not intents (`integrate`, `api-reference`,
+  `patterns`, `setup`, `migration`, …). Feature references split by sub-topic
+  (`guide`, `api-reference`, `advanced`, `examples`).
+- **`index.md` is a lean hub:** shared setup every leaf needs, then a dispatch
+  table with one row per router intent, each an imperative
+  `` `Read: references/<stem>/<leaf>.md` `` pointing at that intent's primary
+  leaf. Intent strings must match Step 1 **exactly** (`feature:mfa`, not `mfa`).
+  A "Then, as needed" list of `Read:` bullets makes the secondary leaves
+  reachable. Every leaf must appear in at least one `Read:` line or it's an
+  orphan.
+- **Lossless + self-contained:** every line of the original file lands in exactly
+  one destination; leaves repeat any shared context inline rather than linking to
+  the hub or each other. If two sections cross-reference too heavily to separate,
+  merge them into one leaf rather than add a link.
+- **Add a routing case** in `evals/routing-cases.json` with the two-hop
+  `expect_refs` (`<name>/index.md` + the intent leaf [+ tooling]), and move the
+  slug from the index-only presence check in `validate-skill.sh` to its grouped
+  loop. For an index-only reference, the presence check is simply
+  `<name>/index.md`.
+
+The router always emits `Read: references/{framework}/index.md` (or
+`{feature}` / `{tooling}`) regardless of whether the target is index-only or a
+leaf group — a global note in Step 4 tells the agent to follow the `index.md`'s
+dispatch table to a leaf if it has one. The reachability and routing-eval
+checkers resolve a leaf-group slug automatically; you don't edit `SKILL.md`'s
+routing tables.
+
 ### Validate
 ```bash
 bash plugins/auth0/skills/auth0/scripts/validate-skill.sh
 python3 scripts/check_router_reachability.py plugins/auth0/skills/auth0
+python3 scripts/check_routing_evals.py plugins/auth0/skills/auth0
 uvx skillsaw --strict
 ```

PLUGIN.md

@@ -32,21 +32,25 @@ pool**:
   loads the 2–3 matching reference files. Routing is file-based and
   deterministic (it reads `package.json`, `composer.json`, `go.mod`,
   `*.csproj`, `pubspec.yaml`, etc.), not a model guess.
-- `references/` is a flat pool of self-contained Markdown files:
-  - `feature-*.md` — a capability spanning frameworks (MFA, Organizations,
+- `references/` is a pool of on-demand Markdown docs. Every reference is a
+  directory `<stem>/` with an `index.md` — either the whole reference
+  (index-only) or, once a reference grows large, a hub `index.md` +
+  document-section leaves (leaf group):
+  - `feature-*/` — a capability spanning frameworks (MFA, Organizations,
     custom domains, ACUL, branding, migration, DPoP).
-  - `framework-*.md` — one SDK/framework integration (React, Next.js, Vue,
+  - `framework-*/` — one SDK/framework integration (React, Next.js, Vue,
     Nuxt, Angular, Express, Flask, FastAPI, Spring Boot, Go, Swift, Android,
     Flutter, Laravel, PHP, ASP.NET Core, React Native, Expo, Ionic, .NET MAUI,
     WinForms, WPF, and more).
-  - `tooling-*.md` — CLI / MCP / Terraform.
-  - `pattern-*.md` — cross-cutting guidance (security, token handling,
+  - `tooling-*/` — CLI / MCP / Terraform.
+  - `pattern-*/` — cross-cutting guidance (security, token handling,
     multi-tenant, rate limiting, common errors).
 
-One skill means one `description` competing for activation, and reference files
-never link to each other (the router loads them in one hop). See
-[`docs/architecture.md`](./docs/architecture.md) for the full rationale, routing
-flow, and the CI-enforced reachability invariant.
+One skill means one `description` competing for activation. Navigation is a
+depth-2 tree: an index-only `index.md` or a leaf-group leaf links to nothing, and
+the only second hop is a leaf-group's hub `index.md` dispatching to a leaf in its
+own directory. See [`docs/architecture.md`](./docs/architecture.md) for the full
+rationale, routing flow, and the CI-enforced reachability invariant.
 
 ---
 
@@ -70,8 +74,9 @@ auth0/agent-skills/
 │       └── skills/
 │           └── auth0/                 # The single unified skill
 │               ├── SKILL.md           # Router (intent → framework → tooling)
-│               ├── references/        # Flat pool: feature-*, framework-*,
-│               │                      #   tooling-*, pattern-* .md files
+│               ├── references/        # feature-*/, framework-*/, tooling-*/,
+│               │                      #   pattern-*/ — every <stem>/ has index.md
+│               │                      #   (index-only or hub + leaves)
 │               ├── assets/            # Templates (e.g. ACUL screens)
 │               └── scripts/           # validate-skill.sh, reachability check
 ├── docs/

docs/architecture.md

@@ -6,23 +6,40 @@
 - Routing is **file-based and deterministic**: the router reads `package.json`,
   `composer.json`, `go.mod`, `*.csproj`, `pubspec.yaml`, etc. — code-driven, not
   a model guess.
-- **No reference file links to any `.md` file.** Claude Code loads the router,
-  then the files it names — one hop. Links between references (or to now-deleted
-  sub-files) are not guaranteed to be followed, so all detection and navigation
-  logic lives in `SKILL.md`, and reference files are self-contained.
+- **Navigation is a depth-2 tree.** Claude Code loads the router, then the files
+  it names. Every reference is a directory `<stem>/` with an `index.md`. An
+  **index-only** reference puts its whole content in `index.md` (one hop from the
+  router, no leaves). A large reference is a **leaf group**: `index.md` is a hub
+  (shared prerequisites + an intent→leaf dispatch table) over document-section
+  leaves. For a leaf group the router reads `index.md`, whose imperative `Read:`
+  dispatch sends the agent to exactly one leaf — two hops. A hub may dispatch
+  **only** to leaves in its own directory; leaves and index-only `index.md` files
+  link to nothing (they are sinks); cross-group links are forbidden. All
+  framework/tooling detection still lives in `SKILL.md`. Leaf groups exist so a
+  large reference doesn't force the agent to load the whole file when it needs
+  one section's worth.
 
 ## Structure
 `plugins/auth0/skills/auth0/`
 - `SKILL.md` — the router (intent → framework → tooling → load).
-- `references/feature-*.md` — a capability spanning frameworks (mfa,
+- `references/feature-*/` — a capability spanning frameworks (mfa,
   organizations, custom-domains, acul, branding, migration, dpop).
-- `references/framework-*.md` — one SDK/framework integration.
-- `references/tooling-*.md` — cli / mcp / terraform.
-- `references/pattern-*.md` — cross-cutting guidance (security, token-handling,
+- `references/framework-*/` — one SDK/framework integration.
+- `references/tooling-*/` — cli / mcp / terraform.
+- `references/pattern-*/` — cross-cutting guidance (security, token-handling,
   multi-tenant, rate-limiting, common-errors).
 - `assets/` — templates (e.g. ACUL screen templates).
 - `scripts/validate-skill.sh` — local structure + routing gate.
 
+Every `framework-*`, `feature-*`, `tooling-*`, and `pattern-*` reference is a
+directory of the same stem (e.g. `framework-swift/`, `feature-branding/`)
+containing an `index.md`. An **index-only** reference has just `index.md`; a
+**leaf group** — when the content is large enough to split — adds document-
+section leaves (`integrate.md`, `api-reference.md`, `patterns.md`, `setup.md`,
+`migration.md`, …) alongside a hub `index.md`. The router routes to the stem
+either way; it always lands on `index.md`, which either *is* the content or
+dispatches to the leaf the task needs.
+
 ## Routing flow
 1. **Intent** — what the developer wants (integrate, feature:*, guidance, debug,
    migrate).
@@ -33,11 +50,15 @@
 4. **Load** 2–3 reference files and follow them.
 
 ## Reachability invariant (CI-enforced)
-`scripts/check_router_reachability.py` asserts every `references/*.md` is
-routable from `SKILL.md` (via template expansion over the known framework and
-tooling value sets) and that no reference file contains an intra-references
-`.md` link (existing target or dead). This runs in the `skillsaw` GitHub Actions
-workflow and inside `validate-skill.sh`.
+`scripts/check_router_reachability.py` asserts the depth-2 tree holds: every
+reference directory is routable from `SKILL.md` (via template expansion over the
+known framework and tooling value sets) and has an `index.md`; every leaf-group
+leaf is reachable from that hub's dispatch; no route points at a missing file;
+and the only second-hop links allowed are a hub `index.md` dispatching to leaves
+**in its own group** — index-only `index.md` files and leaves may contain no
+intra-references `.md` link (existing target or dead), and cross-group links are
+forbidden. This runs in the `skillsaw` GitHub Actions workflow and inside
+`validate-skill.sh`.
 
 To add or extend a capability, see
 [CONTRIBUTING.md](../CONTRIBUTING.md#adding-a-capability-to-the-unified-skill).