Remaining work after #66: loop rename, MCP tool discovery, shortcuts & more

.augment/rules/00-overview.md

@@ -21,6 +21,7 @@ Mitto is a CLI client for the Agent Client Protocol (ACP). It enables terminal-b
 | [websockets/](../docs/devel/websockets/)                           | **WebSocket protocol** (message types, seq numbers, sync, reconnection, delivery verification)      |
 | [workspaces.md](../docs/devel/workspaces.md)                       | Multi-workspace, persistence                                                                        |
 | [follow-up-suggestions.md](../docs/devel/follow-up-suggestions.md) | Action buttons, auxiliary analysis, persistence                                                     |
+| [mcp-tool-discovery.md](../docs/devel/mcp-tool-discovery.md)       | Deterministic MCP tool discovery (stdio/http/sse) vs LLM-introspection fallback                     |
 
 ## Package Structure
 
@@ -35,6 +36,7 @@ internal/client/      → Go client for Mitto REST API + WebSocket (used in test
 internal/config/      → Configuration loading (YAML/JSON)
 internal/conversion/  → Markdown-to-HTML conversion, file link detection
 internal/defense/     → Scanner defense, blocklist, IP metrics (used by web middleware)
+internal/mcpdiscovery/→ Deterministic MCP tool discovery: connects to configured servers (stdio/http/sse) via modelcontextprotocol/go-sdk client; no internal/config or internal/web imports
 internal/mcpserver/   → MCP servers (global debug + per-session)
 internal/processors/  → Command processors (pre/post processing via external commands)
 internal/runner/      → Restricted runner, sandbox execution (go-restricted-runner)

.augment/rules/01-go-conventions.md

@@ -137,4 +137,4 @@ if strings.Contains(err.Error(), "session not started") {
 ## JSON Marshaling
 
 - **Nil vs empty slices**: `json.Marshal` encodes nil as `null`, empty as `[]`. ACP rejects `null` where array is required. Always initialize: `MCPServers: []MCPServer{}`. Mark with `// Must be empty array, not nil — ACP validates this`.
-- **`omitempty` on bool**: Never use `omitempty` on `bool` fields where `false` is meaningful — Go omits `false` as zero value. Example: `PeriodicEnabled bool` must NOT have `omitempty`.
+- **`omitempty` on bool**: Never use `omitempty` on `bool` fields where `false` is meaningful — Go omits `false` as zero value. Example: `LoopEnabled bool` must NOT have `omitempty`.

.augment/rules/02-session.md

@@ -30,7 +30,7 @@ keywords:
 | `Lock`               | Session locking, heartbeat, cleanup         | Yes (mutex + goroutine) |
 | `Queue`              | Message queue for busy agent                | Yes (mutex)             |
 | `ActionButtonsStore` | Follow-up suggestions persistence           | Yes (mutex)             |
-| `PeriodicStore`      | Periodic prompt config per session          | Yes (mutex)             |
+| `LoopStore`      | Loop prompt config per session          | Yes (mutex)             |
 | `Flags`              | Available feature flags registry            | N/A (read-only)         |
 
 ## Immediate Persistence (Web Interface)
@@ -117,9 +117,9 @@ lock.SetWaitingPermission("File write")  // During permission request
 
 **Important**: Queue configuration is **global/workspace-scoped**, NOT per-session. See [docs/devel/message-queue.md](../docs/devel/message-queue.md) for config options, REST API, WebSocket notifications, and title auto-generation.
 
-## Periodic Prompts (PeriodicStore)
+## Loop Prompts (LoopStore)
 
-Stored in `periodic.json`. Only top-level sessions may have periodic prompts (child → 400).
+Stored in `loop.json`. Only top-level sessions may have loop prompts (child → 400).
 
 **Key fields**:
 - `PromptName` — references workspace prompt by name (resolved at send time via cache)
@@ -128,7 +128,7 @@ Stored in `periodic.json`. Only top-level sessions may have periodic prompts (ch
 - `DelaySeconds` — wait after agent idle before firing (onCompletion only)
 - `MaxDurationSeconds` — wall-clock cap since first run
 
-**Critical**: Changing `PeriodicStore.Update()` signature requires updating BOTH `session_periodic_api.go` (PATCH handler) AND `mcpserver/server.go` (MCP tool) — both call `Update()`.
+**Critical**: Changing `LoopStore.Update()` signature requires updating BOTH `session_loop_api.go` (PATCH handler) AND `mcpserver/server.go` (MCP tool) — both call `Update()`.
 
 ## Auxiliary Package
 

.augment/rules/04-component-extraction.md

@@ -94,3 +94,11 @@ Place in implementation file to catch interface breaking changes:
 // Verify component satisfies interface at compile time
 var _ conversation.SharedProcess = (*sharedSessionAnalyzer)(nil)
 ```
+
+## Post-Extraction Cleanup
+
+After extracting a component, **remove unused delegators** from original file:
+- **Scan before merge**: Run `golangci-lint run ./internal/conversation` to find unused methods
+- **Remove both**: Delegator method + corresponding test if only that method used the test
+- **Keep pattern**: Only delegators actively called by other packages or public API
+- **Example**: If `ConfigManager.GetConfig()` is extracted and `BackgroundSession.GetConfig()` delegator is never called externally, remove both (unless it's part of exported `SessionManager` interface)

.augment/rules/05-msghooks.md

@@ -46,7 +46,7 @@ when:                  # required block — BOTH on: and match: are required
     everyNTurns: 3     # fire every N responses; everyNTokens: 15000; afterInterval: 5m (all AND-logic)
 priority: 100          # lower = earlier
 enabled: true          # false = never loads (build-time gate)
-enabledWhen: 'acp.matchesServerType("augment") && !session.isPeriodic'  # CEL runtime gate
+enabledWhen: 'acp.matchesServerType("augment") && !session.isLoop'  # CEL runtime gate
 onError: skip          # skip | fail
 
 # Text-mode only (forbidden for agentResponded/agentIdle):
@@ -130,7 +130,7 @@ Key CEL variables/functions (full reference in `docs/config/processors.md`):
 | Context                 | Examples                                                                    |
 | ----------------------- | --------------------------------------------------------------------------- |
 | `acp.*`                 | `acp.matchesServerType("augment")`, `acp.name`, `acp.type`, `acp.tags`     |
-| `session.*`             | `session.isPeriodic`, `session.isChild`, `session.id`                       |
+| `session.*`             | `session.isLoop`, `session.isChild`, `session.id`                       |
 | `Session.ModelTags`     | `Session.HasModelTag("smart")`, `"smart" in Session.ModelTags` — current model's tags from `models:` profiles (template: `{{ if Model "smart" }}`); empty when model unknown |
 | `workspace.*`           | `workspace.hasUserDataSchema`, `workspace.hasMittoRC`, `workspace.hasMetadataDescription`, `workspace.folder` |
 | `children.*`            | `children.exists`, `children.count`, `children.mcp_count`, `children.promptingCount`, `children.idleCount` |

.augment/rules/07-prompts.md

@@ -117,7 +117,7 @@ a plain conversation with no pre-selected issue.
 4. Gate **every** `bd` command and id-specific `git grep` behind
    `{{ if $target }} … {{ end }}` — mode 3 must emit **zero** `bd` calls.
 
-**Exemplars**: `beads-issue-investigate`, `beads-issue-discuss`,
+**Exemplars**: `beads-issue-investigate`, `beads-issue-assess`,
 `beads-issue-status`, `beads-issue-resolved`, `beads-issue-work`.
 
 **Guard tests**: `*ThreeModeTargetResolution` tests + `TestBuiltinPrompts_NoDeprecatedMittoVars`
@@ -127,13 +127,13 @@ Full recipe: [docs/config/prompts.md § Context-adaptive prompts (three modes)](
 
 ## Key Types
 
-`WebPrompt`: Name, Prompt, Description, Group, BackgroundColor, Icon, Source ("builtin"|"file"|"settings"|"workspace"), Enabled (*bool: nil=enabled, false=disabled), EnabledWhen (CEL, server-side only), Periodic (non-nil = periodic conversation), Singleton (bool: `true` = no concurrent conversation instances for this prompt in the same working dir; see below).
+`WebPrompt`: Name, Prompt, Description, Group, BackgroundColor, Icon, Source ("builtin"|"file"|"settings"|"workspace"), Enabled (*bool: nil=enabled, false=disabled), EnabledWhen (CEL, server-side only), Loop (non-nil = loop conversation), Singleton (bool: `true` = no concurrent conversation instances for this prompt in the same working dir; see below).
 
 ### Singleton Prompts (find-or-route)
 
 A prompt with `singleton: true` must not have more than one non-archived conversation per working dir. A session records the prompt that created it in `session.Metadata.OriginPromptName` at create time (set on `POST /api/sessions` from `initial_prompt_name`/`origin_prompt_name`). When a singleton prompt is launched, `HandleCreateSession` (`internal/web/handlers/session_create.go`) scans existing non-archived sessions by `(WorkingDir, OriginPromptName)` under a keyed lock (`lockSingleton`); on a match it reuses that conversation instead of creating a new one — re-seeding the queue if idle, focus-only if busy — and responds with `reused: true`. The frontend threads `reused` through `useWebSocket.js` → `useConversationSeeding.js` and shows a "Reusing existing ..." toast instead of "Started ..." (`useBeadsIntegration.js`, `app.js`). Applied to the builtin beadsList maintenance prompts (overview, reevaluate, cleanup-stale, group-epics, status-all-inprogress) — deliberately **not** to "Start working on ready", since concurrent work-starting conversations are legitimate.
 
-`PromptPeriodic` (YAML `periodic:`): `value`/`unit`/`at` (schedule period), `maxIterations`, plus the on-completion fields `trigger` (`schedule` default | `onCompletion`), `delay` (int seconds for onCompletion; clamped to the global floor), and `maxDuration` (duration string e.g. `4h`; wall-clock cap from the first run). `MaxIterations` caps scheduled runs; effective cap = min(prompt maxIterations, config default 100, hardcoded 1000). Backend auto-disables (not archives) when either the iteration cap or `maxDuration` is hit.
+`PromptLoop` (YAML `loop:`): `value`/`unit`/`at` (schedule period), `maxIterations`, plus the on-completion fields `trigger` (`schedule` default | `onCompletion`), `delay` (int seconds for onCompletion; clamped to the global floor), and `maxDuration` (duration string e.g. `4h`; wall-clock cap from the first run). `MaxIterations` caps scheduled runs; effective cap = min(prompt maxIterations, config default 100, hardcoded 1000). Backend auto-disables (not archives) when either the iteration cap or `maxDuration` is hit.
 
 ## Merging & Caching
 
@@ -145,7 +145,7 @@ A prompt with `singleton: true` must not have more than one non-archived convers
 
 ## Menu-Driven Prompt Sends (Named-Prompt Mechanism)
 
-All menus (prompts, beadsIssues, beadsList) send `prompt_name` only — never the full body. Frontend helpers in `useConversationSeeding.js`: `seedConversationWithPrompt()` (existing session), `startConversationWithPrompt()` (new ± periodic), `makePeriodicNow()` (convert to periodic). Backend resolves name at dispatch via `resolvePromptByName()` in target workspace context; the body is then **Go-template rendered** (if it contains `{{`) before `${VAR}` substitution. **Anti-pattern**: never POST resolved text to `/api/sessions/{id}/queue` — send `prompt_name` instead.
+All menus (prompts, beadsIssues, beadsList) send `prompt_name` only — never the full body. Frontend helpers in `useConversationSeeding.js`: `seedConversationWithPrompt()` (existing session), `startConversationWithPrompt()` (new ± loop), `makeLoopNow()` (convert to loop). Backend resolves name at dispatch via `resolvePromptByName()` in target workspace context; the body is then **Go-template rendered** (if it contains `{{`) before `${VAR}` substitution. **Anti-pattern**: never POST resolved text to `/api/sessions/{id}/queue` — send `prompt_name` instead.
 
 ## MCP Prompt Tools
 
@@ -217,11 +217,11 @@ parameters:
 
 ## Iteration.IsUninterrupted (mitto-5xjn)
 
-`{{ .Iteration.IsUninterrupted }}` is `true` only on a **scheduled** (non-forced, non-FreshContext) periodic run that directly follows another such run with nothing in between — no user interjection, no forced "run now", no FreshContext, same process lifetime.
+`{{ .Iteration.IsUninterrupted }}` is `true` only on a **scheduled** (non-forced, non-FreshContext) loop run that directly follows another such run with nothing in between — no user interjection, no forced "run now", no FreshContext, same process lifetime.
 
 **Reset boundaries** (set marker to false):
 - Archive/unarchive, GC suspend/resume, process restart
 - ACP process reinit/restart
-- Periodic loop config change / pause / re-enable
+- Loop loop config change / pause / re-enable
 
 **Authoring rule**: compact "continue" branch must carry durable re-anchor (one-line goal + file/bead ref). Always render verbose form when `IsFirst || !IsUninterrupted` to reset context after interruptions.

.augment/rules/08-config.md

@@ -21,6 +21,8 @@ keywords:
   - folder deduplication
   - LoadFolders
   - SaveFolders
+  - ShortcutButton
+  - global shortcuts
 ---
 
 # Configuration System
@@ -117,6 +119,18 @@ Prompt `preferredModels` field (see `07-prompts.md`) references these profiles b
 
 Agent metadata can pre-seed these at discovery: `metadata.yaml` `defaults.constraints` (plus `defaults.env`/`tags`/`autoApprove`) map onto `ACPServer.Constraints`/`Env`/`Tags`/`AutoApprove` via `seedACPServerDefaults` (see [03-cli-acp.md](03-cli-acp.md#agent-defaults-seeded-at-discovery)). Seeding is request-wins (user-supplied values are not overwritten).
 
+## Global Shortcuts
+
+Global shortcut buttons (`shortcuts:` in `settings.json`) mirror per-folder shortcuts (`folders.json`) and are merged with them **at render time** on the frontend — the backend stores and serves each level independently:
+
+- Type: `config.ShortcutButton{Icon, Prompt}` (`internal/config/folders.go`) — `Prompt` is a workspace prompt name, `Icon` an optional `PROMPT_ICONS` key.
+- Sections (map key in both global and folder JSON): `conversations`, `beadsIssue`, `tasksList`.
+- API: `GET/PUT /api/global/shortcuts` (`internal/web/handlers/global_shortcuts.go`) mirrors the folder shortcuts endpoint; GET also returns the available `Prompts` so the editor needs only one request.
+- `buildNewSettings` must preserve `shortcuts:` so an unrelated Settings save never wipes global shortcuts.
+- Defaults for new installs are seeded in embedded `config/config.default.yaml` (`shortcuts:` key) — written to `settings.json` on first run only; existing installs are untouched.
+
+Frontend merge/dedupe logic (duplicated in `BeadsView.js` ×2 and `app.js`): global list first, then folder entries whose `prompt` isn't already in the global list. See `25-web-frontend-components.md` for the shared `ShortcutsEditor` UI component.
+
 ## WorkspaceSettings Override Pattern
 
 `WorkspaceSettings.ACPCommandOverride`: set default from server map, then apply override. See `internal/config/merger.go` for `GenericMerger[T]`.

.augment/rules/11-web-backend-sequences.md

@@ -62,7 +62,7 @@ When a tool call or thought arrives from ACP, force-flush the MarkdownBuffer:
 | Method        | Behavior                             | When to Use                           |
 | ------------- | ------------------------------------ | ------------------------------------- |
 | `Flush()`     | Force flush, ignores markdown state  | Tool calls, thoughts, prompt complete |
-| `SafeFlush()` | Only flush if not in table/list/code | Periodic/timeout flushes              |
+| `SafeFlush()` | Only flush if not in table/list/code | Loop/timeout flushes              |
 
 ## Observer Patterns