Add progressive orientation discovery

docs/ai-coding-agents/claude-code-plugin.md

@@ -10,7 +10,7 @@ The installer extracts a self-contained Claude marketplace below the platform
 user-data directory, registers it with `claude plugin marketplace add`, and
 installs `tapper@tapper-local`. The plugin registers `tap mcp`, blocks direct
 agent use of the Tapper CLI except harmless help/version/completion probes, and
-orients through the active flight and covered KEG instructions. Its guard runs
+orients through the active flight, compact KEG discovery, and targeted settings instructions. Its guard runs
 as `tap hook pre-tool-use`, so the current `tap` binary must remain on `PATH`.
 
 Install the optional developer workflow separately:

docs/ai-coding-agents/mcp-setup.md

@@ -93,7 +93,7 @@ agent to inspect flights through MCP, ask the user to run `tap use --flight
 | `backlinks` | Find nodes linking to a node |
 | `links` | List outgoing links from a node |
 | `info` | Show concise diagnostics for the resolved keg |
-| `keg_settings` | Read keg configuration |
+| `keg_settings` | Read targeted minimal config for one or more selected KEGs; `minimal=false` reads one complete config |
 | `stats` | Show node statistics |
 
 ### Write

docs/ai-coding-agents/orient.md

@@ -10,10 +10,10 @@ operating against tapper KEGs. The same bytes are reachable three ways: the
 The payload always starts with KEG system context:
 
 1. KEG purpose and core rules.
-2. Available KEGs, including role, source, and the active flight cap when a
-   flight is selected.
+2. Available KEGs, including each canonical reference, title, concise summary,
+   role, source, and active flight cap when a flight is selected.
 3. Flight title and instructions, when a flight is active.
-4. KEG-level instructions from each available KEG config.
+4. A prompt to request targeted KEG settings before operating.
 5. Canonical Tapper agent guidance: linking, snapshots, tool inventory, and
    troubleshooting.
 
@@ -34,20 +34,35 @@ refreshes the server-owned session orientation.
 commands ignore flight cover caps and use normal authorization; MCP tools
 enforce the most recently published orientation.
 
-## KEG Instructions
+## Progressive KEG Guidance
 
-KEG-specific guidance belongs on the KEG config itself:
+`summary` and `instructions` have distinct roles in a KEG config:
 
 ```yaml
 kegv: 2025-07
 title: Engineering
+summary: Architecture, delivery, and operational knowledge for engineering.
 instructions: |
   Prefer architecture notes before implementation notes.
   Snapshot any node before changing public API guidance.
 ```
 
-When the KEG is available in the active orient context, those instructions
-render in the `## KEG Instructions` section before canonical Tapper guidance.
+`summary` is the concise discovery description shown by aggregate orientation.
+It should help an agent decide whether the KEG is relevant and is not
+automatically truncated. `instructions` is targeted operational guidance.
+Aggregate orientation never includes it, even under `full_access`.
+
+After selecting relevant KEGs, call `keg_settings` with either `keg` or
+`kegs`. Minimal mode is the default and returns title, summary, updated
+metadata, and instructions. Up to 100 canonical references may be expanded
+together:
+
+```json
+{"kegs":["@foldwise/dev","@foldwise/engineering"]}
+```
+
+`keg` and `kegs` are mutually exclusive. Multiple KEGs require minimal mode;
+`minimal=false` continues to return the complete config for exactly one KEG.
 
 ## MCP Tool
 
@@ -91,7 +106,8 @@ tap orient --flight @acme/+release-42
 
 `--flight` is a root persistent CLI flag available on commands that accept
 `--keg`. It is free-form and suppresses filesystem completion; it is not part
-of any MCP tool schema.
+of any ordinary MCP tool schema. MCP flight selection is fixed by the human
+session boundary and cannot be overridden by `orient` or `keg_settings`.
 
 ## Byte-Equivalence Guarantee
 

docs/configuration/keg-config.md

@@ -34,6 +34,12 @@ Common keg fields:
 - `indexes`
 - `schemaPolicy`
 
+Use `summary` for a concise discovery description: aggregate orientation uses
+it to help agents identify relevant KEGs and does not automatically truncate
+it. Use `instructions` for targeted operational guidance. Instructions are
+loaded only after an agent explicitly selects the KEG through `keg_settings`;
+they are not included in aggregate orientation.
+
 `schemaPolicy` has three actor-specific modes: `human`, `agent`, and `api`.
 Each accepts `off`, `warn`, or `block`. When omitted, human writes default to
 `warn`, while agent and API writes default to `block`. Archive imports and

integrations/content/agent-orient.md

@@ -1,9 +1,11 @@
 # tapper
 
 Interact with Tapper KEGs (Knowledge Exchange Graphs) through the native MCP
-server. At the start of KEG work, call `mcp__tapper__orient` and treat the
-returned active flight, cover, flight instructions, and covered-KEG
-instructions as the authoritative context for the session.
+server. At the start of KEG work, call `mcp__tapper__orient`, identify the
+relevant covered KEGs from their titles and summaries, then call
+`mcp__tapper__keg_settings` for those KEGs before operating. Treat the active
+flight, cover, flight instructions, and targeted KEG instructions as the
+authoritative context for the session.
 
 ## Rules
 
@@ -27,14 +29,16 @@ returned by orientation to work across KEGs without changing directories or
 restarting the MCP server.
 
 - `mcp__tapper__orient` — returns the active flight, its cover and instructions,
-  covered KEG instructions, and canonical safety guidance.
+  compact KEG discovery metadata, and canonical safety guidance.
+- `mcp__tapper__keg_settings` — returns targeted title, summary, updated
+  metadata, and instructions for one or more selected KEGs.
 - `mcp__tapper__info` — returns concise diagnostics for a covered KEG.
 - `mcp__tapper__keg_list` — lists the KEGs exposed by configured hubs.
 
 ## Bootstrapping a session
 
-Call `mcp__tapper__orient` first. Follow the pinned flight and KEG instructions
-it returns. When no flight is selected, the local MCP server connects in a
+Call `mcp__tapper__orient` first, then load the selected KEG instructions with
+`mcp__tapper__keg_settings`. When no flight is selected, the local MCP server connects in a
 recovery-only state: KEG tools are locked, while `mcp__tapper__list_flights`
 and `mcp__tapper__flight_show` remain available for discovery. Ask the user to
 select a flight in Tapper configuration, then call `mcp__tapper__orient` again.

integrations/content/tool-inventory.md

@@ -12,6 +12,7 @@
 | `mcp__tapper__backlinks`                              | Inbound links to a node.                                                                                                                                 |
 | `mcp__tapper__graph`                                  | Graph traversal for multi-hop relationships.                                                                                                             |
 | `mcp__tapper__list_indexes`, `mcp__tapper__index_cat` | Read generated index files (tag index, changelog, and others).                                                                                           |
+| `mcp__tapper__keg_settings`                           | Read targeted title, summary, updated metadata, and instructions for one or more selected KEGs; batches accept up to 100 canonical references.          |
 
 Pass `id_only: true` to `grep` and `tags` when you only need IDs for follow-up
 reads — it keeps token consumption bounded on large result sets.

integrations/rendered/claude/tapper-dev/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "tapper-dev",
   "description": "Optional Plan to Code to Review to Commit workflow for Tapper-enabled development.",
-  "version": "0.35.0",
+  "version": "0.0.0-dev",
   "author": {
     "name": "Jared Rickert"
   },

integrations/rendered/claude/tapper-dev/skills/tapper-dev/SKILL.md

@@ -10,7 +10,7 @@ The baseline `tapper` plugin is required: call `mcp__tapper__orient` before the
 workflow and stop with an actionable prerequisite error if that tool is not
 available.
 
-The active flight and covered KEG instructions remain authoritative. Use
+The active flight and explicitly loaded, targeted KEG instructions remain authoritative. Use
 lifecycle types, fields, and state transitions only when the active flight,
 KEG instructions, and current schemas support them. Never invent a schema or
 embed a project-specific KEG target.

integrations/rendered/claude/tapper/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "tapper",
   "description": "MCP-first Tapper KEG access, flight orientation, and safety guidance.",
-  "version": "0.35.0",
+  "version": "0.0.0-dev",
   "author": {
     "name": "Jared Rickert"
   },

integrations/rendered/claude/tapper/skills/tapper/SKILL.md

@@ -6,9 +6,11 @@ description: Orient to Tapper flights and operate on KEGs through MCP-first safe
 # tapper
 
 Interact with Tapper KEGs (Knowledge Exchange Graphs) through the native MCP
-server. At the start of KEG work, call `mcp__tapper__orient` and treat the
-returned active flight, cover, flight instructions, and covered-KEG
-instructions as the authoritative context for the session.
+server. At the start of KEG work, call `mcp__tapper__orient`, identify the
+relevant covered KEGs from their titles and summaries, then call
+`mcp__tapper__keg_settings` for those KEGs before operating. Treat the active
+flight, cover, flight instructions, and targeted KEG instructions as the
+authoritative context for the session.
 
 ## Rules
 
@@ -32,14 +34,16 @@ returned by orientation to work across KEGs without changing directories or
 restarting the MCP server.
 
 - `mcp__tapper__orient` — returns the active flight, its cover and instructions,
-  covered KEG instructions, and canonical safety guidance.
+  compact KEG discovery metadata, and canonical safety guidance.
+- `mcp__tapper__keg_settings` — returns targeted title, summary, updated
+  metadata, and instructions for one or more selected KEGs.
 - `mcp__tapper__info` — returns concise diagnostics for a covered KEG.
 - `mcp__tapper__keg_list` — lists the KEGs exposed by configured hubs.
 
 ## Bootstrapping a session
 
-Call `mcp__tapper__orient` first. Follow the pinned flight and KEG instructions
-it returns. When no flight is selected, the local MCP server connects in a
+Call `mcp__tapper__orient` first, then load the selected KEG instructions with
+`mcp__tapper__keg_settings`. When no flight is selected, the local MCP server connects in a
 recovery-only state: KEG tools are locked, while `mcp__tapper__list_flights`
 and `mcp__tapper__flight_show` remain available for discovery. Ask the user to
 select a flight in Tapper configuration, then call `mcp__tapper__orient` again.
@@ -60,6 +64,7 @@ no KEGs.
 | `mcp__tapper__backlinks`                              | Inbound links to a node.                                                                                                                                 |
 | `mcp__tapper__graph`                                  | Graph traversal for multi-hop relationships.                                                                                                             |
 | `mcp__tapper__list_indexes`, `mcp__tapper__index_cat` | Read generated index files (tag index, changelog, and others).                                                                                           |
+| `mcp__tapper__keg_settings`                           | Read targeted title, summary, updated metadata, and instructions for one or more selected KEGs; batches accept up to 100 canonical references.          |
 
 Pass `id_only: true` to `grep` and `tags` when you only need IDs for follow-up
 reads — it keeps token consumption bounded on large result sets.

integrations/rendered/codex/tapper-dev/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "tapper-dev",
-  "version": "0.35.0",
+  "version": "0.0.0-dev",
   "description": "Optional Plan to Code to Review to Commit workflow for Tapper-enabled development.",
   "author": {
     "name": "Jared Rickert",

integrations/rendered/codex/tapper-dev/skills/tapper-dev/SKILL.md

@@ -10,7 +10,7 @@ The baseline `tapper` plugin is required: call `mcp__tapper__orient` before the
 workflow and stop with an actionable prerequisite error if that tool is not
 available.
 
-The active flight and covered KEG instructions remain authoritative. Use
+The active flight and explicitly loaded, targeted KEG instructions remain authoritative. Use
 lifecycle types, fields, and state transitions only when the active flight,
 KEG instructions, and current schemas support them. Never invent a schema or
 embed a project-specific KEG target.

integrations/rendered/codex/tapper/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "tapper",
-  "version": "0.35.0",
+  "version": "0.0.0-dev",
   "description": "MCP-first Tapper KEG access, flight orientation, and safety guidance.",
   "author": {
     "name": "Jared Rickert",

integrations/rendered/codex/tapper/skills/tapper/SKILL.md

@@ -6,9 +6,11 @@ description: Orient to Tapper flights and operate on KEGs through MCP-first safe
 # tapper
 
 Interact with Tapper KEGs (Knowledge Exchange Graphs) through the native MCP
-server. At the start of KEG work, call `mcp__tapper__orient` and treat the
-returned active flight, cover, flight instructions, and covered-KEG
-instructions as the authoritative context for the session.
+server. At the start of KEG work, call `mcp__tapper__orient`, identify the
+relevant covered KEGs from their titles and summaries, then call
+`mcp__tapper__keg_settings` for those KEGs before operating. Treat the active
+flight, cover, flight instructions, and targeted KEG instructions as the
+authoritative context for the session.
 
 ## Rules
 
@@ -32,14 +34,16 @@ returned by orientation to work across KEGs without changing directories or
 restarting the MCP server.
 
 - `mcp__tapper__orient` — returns the active flight, its cover and instructions,
-  covered KEG instructions, and canonical safety guidance.
+  compact KEG discovery metadata, and canonical safety guidance.
+- `mcp__tapper__keg_settings` — returns targeted title, summary, updated
+  metadata, and instructions for one or more selected KEGs.
 - `mcp__tapper__info` — returns concise diagnostics for a covered KEG.
 - `mcp__tapper__keg_list` — lists the KEGs exposed by configured hubs.
 
 ## Bootstrapping a session
 
-Call `mcp__tapper__orient` first. Follow the pinned flight and KEG instructions
-it returns. When no flight is selected, the local MCP server connects in a
+Call `mcp__tapper__orient` first, then load the selected KEG instructions with
+`mcp__tapper__keg_settings`. When no flight is selected, the local MCP server connects in a
 recovery-only state: KEG tools are locked, while `mcp__tapper__list_flights`
 and `mcp__tapper__flight_show` remain available for discovery. Ask the user to
 select a flight in Tapper configuration, then call `mcp__tapper__orient` again.
@@ -60,6 +64,7 @@ no KEGs.
 | `mcp__tapper__backlinks`                              | Inbound links to a node.                                                                                                                                 |
 | `mcp__tapper__graph`                                  | Graph traversal for multi-hop relationships.                                                                                                             |
 | `mcp__tapper__list_indexes`, `mcp__tapper__index_cat` | Read generated index files (tag index, changelog, and others).                                                                                           |
+| `mcp__tapper__keg_settings`                           | Read targeted title, summary, updated metadata, and instructions for one or more selected KEGs; batches accept up to 100 canonical references.          |
 
 Pass `id_only: true` to `grep` and `tags` when you only need IDs for follow-up
 reads — it keeps token consumption bounded on large result sets.

pkg/integrations/renderdata/developer/workflow.md

@@ -5,7 +5,7 @@ The baseline `tapper` plugin is required: call `mcp__tapper__orient` before the
 workflow and stop with an actionable prerequisite error if that tool is not
 available.
 
-The active flight and covered KEG instructions remain authoritative. Use
+The active flight and explicitly loaded, targeted KEG instructions remain authoritative. Use
 lifecycle types, fields, and state transitions only when the active flight,
 KEG instructions, and current schemas support them. Never invent a schema or
 embed a project-specific KEG target.

pkg/mcp/tools_orient_test.go

@@ -36,7 +36,8 @@ func TestMCP_OrientTool_ReturnsSharedKegSystemPayload(t *testing.T) {
 	require.NotContains(t, text, "`tap ")
 	require.NotContains(t, text, "## Active KEG")
 	require.Contains(t, text, "## Available KEGs")
-	require.Contains(t, text, "## KEG Instructions")
+	require.NotContains(t, text, "## KEG Instructions")
+	require.Contains(t, text, "Call `keg_settings`")
 	require.Contains(t, text, "## Guidance")
 	require.Contains(t, text, "# Linking conventions")
 	require.Contains(t, text, "# Snapshot policy")

pkg/mcp/tools_read.go

@@ -2,6 +2,7 @@ package mcp
 
 import (
 	"context"
+	"fmt"
 
 	sdkmcp "github.com/modelcontextprotocol/go-sdk/mcp"
 
@@ -255,8 +256,9 @@ func registerLinks(srv *sdkmcp.Server, tap *tapper.Tap, defaults KegDefaults) {
 // --- keg_settings ---
 
 type kegSettingsInput struct {
-	Keg     string `json:"keg,omitempty" jsonschema:"keg alias (uses default if empty)"`
-	Minimal *bool  `json:"minimal,omitempty" jsonschema:"return only core config fields (default true)"`
+	Keg     string   `json:"keg,omitempty" jsonschema:"keg alias (uses default if empty)"`
+	Kegs    []string `json:"kegs,omitempty" jsonschema:"canonical keg references to read together (maximum 100; minimal mode only)"`
+	Minimal *bool    `json:"minimal,omitempty" jsonschema:"return only core config fields (default true)"`
 }
 
 func registerKegSettings(srv *sdkmcp.Server, tap *tapper.Tap, defaults KegDefaults) {
@@ -272,10 +274,28 @@ func registerKegSettings(srv *sdkmcp.Server, tap *tapper.Tap, defaults KegDefaul
 		if in.Minimal != nil {
 			minimal = *in.Minimal
 		}
+		if in.Keg != "" && in.Kegs != nil {
+			return errorResult(fmt.Errorf("keg and kegs are mutually exclusive")), nil, nil
+		}
+		if in.Kegs != nil {
+			if len(in.Kegs) == 0 || len(in.Kegs) > 100 {
+				return errorResult(fmt.Errorf("kegs must contain 1 to 100 canonical references")), nil, nil
+			}
+			if !minimal && len(in.Kegs) != 1 {
+				return errorResult(fmt.Errorf("minimal=false requires exactly one keg")), nil, nil
+			}
+		}
+		target := in.Keg
+		if !minimal && len(in.Kegs) == 1 {
+			target = in.Kegs[0]
+		}
 		opts := tapper.KegSettingsOptions{
-			KegTargetOptions: resolveKegTarget(ctx, in.Keg, defaults),
+			KegTargetOptions: resolveKegTarget(ctx, target, defaults),
 			Minimal:          minimal,
 		}
+		if minimal {
+			opts.Kegs = in.Kegs
+		}
 		result, err := tap.KegSettings(ctx, opts)
 		if err != nil {
 			return errorResult(err), nil, nil