{"schema":"maestro/commit/1","summary":"align docs taxonomy cleanup","authority":"manual"}

Author: yvette-carlisle

README.md

@@ -136,7 +136,8 @@ First-run onboarding checklist:
 - Voxit uses request buttons to guide you through the permission prompts in sequence (Microphone → Accessibility → Input Monitoring); grant each permission and re-check when prompted.
 - Verify paste flow after permission grant and restart the app if needed.
 
-For the full guided sequence, see [First Run](docs/runbook/first-run.md).
+For the full guided sequence, see
+[First-Run Onboarding](docs/runbook/first-run-onboarding.md).
 
 The app saves updates to the same `config.toml` path when settings are changed.
 
@@ -172,10 +173,9 @@ The app saves updates to the same `config.toml` path when settings are changed.
 
 ### Docs
 
-- [Documentation Index](docs/index.md) routes to spec, runbook, reference, and decision docs.
+- [Documentation Index](docs/index.md) routes to spec, runbook, and reference docs.
 - [Runtime Spec](docs/spec/runtime.md) is the normative runtime contract.
-- [First Run](docs/runbook/first-run.md) covers sign-in, permission grants, and paste validation.
-- [Repository Layout](docs/reference/repository-layout.md) maps the current repo surfaces.
+- [Workspace Layout](docs/reference/workspace-layout.md) maps the current repo surfaces.
 
 ## Support Me
 

docs/decisions/index.md

@@ -9,15 +9,17 @@ workflows. The split below is by question type, not by human-versus-agent audien
 
 - Read `README.md` first when you need the repository scope, platform target, or
   top-level runtime summary.
+- Use `cargo make` whenever an equivalent repo task exists. When task details matter,
+  inspect `Makefile.toml` directly.
 - Read `docs/policy.md` for document contracts, placement rules, and naming rules.
-- Use `cargo make` whenever an equivalent repo task exists. Inspect `Makefile.toml`
-  directly when task names or execution entrypoints matter.
+- Read `Makefile.toml` when the task depends on repo task names or execution entrypoints.
 - Then choose one primary lane:
   - `docs/spec/index.md` when the question is "what must be true?"
   - `docs/runbook/index.md` when the question is "which sequence should I execute?"
   - `docs/reference/index.md` when the question is "how is it currently organized or
     implemented?"
-  - `docs/decisions/index.md` when the question is "why is it shaped this way?"
+- Use `docs/plans/` only when a planning tool or execution workflow explicitly points to
+  a saved plan artifact there.
 
 ## Routing matrix
 
@@ -27,17 +29,16 @@ workflows. The split below is by question type, not by human-versus-agent audien
   -> `docs/runbook/`
 - Need current repository layout, ownership boundaries, or implementation surface maps ->
   `docs/reference/`
-- Need durable rationale, tradeoffs, or historical consequences -> `docs/decisions/`
 - Need repo task names or automation entrypoints -> `Makefile.toml`
 - Need documentation placement or authoring rules -> `docs/policy.md`
+- Need a planning-tool artifact or saved execution plan -> `docs/plans/`
 
 ## Retrieval rules
 
 - Optimize for agent routing and execution, not narrative flow.
 - Keep one authoritative document per topic. Link instead of copying.
-- Runtime and behavior authority lives in code plus `docs/spec/`. Runbook, reference,
-  and decision docs explain usage, current state, and rationale, but do not override the
-  governing spec.
+- Keep runtime authority explicit: application and package crates plus `docs/spec/`
+  outrank runbook, reference, and plan artifacts.
 - Start each document with a short routing header that says what the document is for,
   when to read it, and what it does not cover.
 - Keep links explicit and stable.

docs/index.md

@@ -0,0 +1,51 @@
+# Audio Input Device Selection Design
+
+## Scope
+
+Document the implemented behavior for choosing and persisting the microphone used for recording, including fallback and UX constraints.
+
+## UX
+
+- The runtime control panel shows a microphone section with:
+  - A **Refresh microphones** button to re-enumerate available input devices.
+  - A **Input device** combo box rendered from discovered devices and a **System default** option.
+- Combo text conventions:
+  - `System default` corresponds to no explicit device override.
+  - Discovered item labels follow `name (id)`.
+  - If the selected ID is no longer in the list, the fallback label uses `Device #<id>` or the persisted `audio.input_device_name`.
+- Changing selection updates config immediately and persists it.
+- Recording status should expose fallback when it happens:
+  - e.g., `Selected microphone unavailable. Falling back to default: <name>.`
+
+## Config contract
+
+- Keys under `[audio]`:
+  - `audio.input_device_id` (number, `0` => use system default).
+  - `audio.input_device_name` (string, best-effort human-readable label).
+- Default state:
+  - `audio.input_device_id = 0`.
+  - `audio.input_device_name = ""`.
+- Persistence:
+  - Both keys are serialized in config writes.
+  - On load, missing/invalid keys fall back to defaults.
+- Resolution rules:
+  - If `audio.input_device_id == 0`, recording uses the platform default microphone.
+  - If non-zero, app attempts that ID.
+
+## Fallback and constraints
+
+- If configured `audio.input_device_id` is invalid, disconnected, or lacks input scope at session start:
+  - selection falls back to default input device.
+  - recording proceeds with `fallback_to_default = true`.
+  - status/logging reports the fallback.
+- If the device enumeration call fails or returns empty:
+  - combo still supports **System default** path.
+  - no devices can be shown/selected from the list.
+- Non-macOS paths currently do not support mic capture and are not in-scope for picker functionality.
+
+## Acceptance criteria
+
+- Picker always presents **System default** and any available input-capable device list.
+- Selection persists and survives restart via `audio.input_device_name` + `audio.input_device_id`.
+- Session start is deterministic when configured devices are unavailable.
+- Fallback behavior is transparent in status/log output.

docs/plans/.gitkeep

@@ -0,0 +1,56 @@
+# Audio Input Device Selection Implementation Plan
+
+## Goal
+
+Deliver and document the implemented microphone picker behavior, aligned to current code paths and config contract.
+
+## High-level execution steps
+
+1. Confirm configuration parsing and serialization for audio keys
+   - Ensure `audio.input_device_id` and `audio.input_device_name` are preserved in `AudioConfig`.
+   - Keep defaults as:
+     - `input_device_id = 0`
+     - `input_device_name = ""`
+   - Keep parse/serialize behavior unchanged except for explicit persistence of these keys.
+
+2. Confirm audio module selection path
+   - Keep `list_input_devices()` returning all input-capable devices (sorted for deterministic order).
+   - Keep `resolve_input_device()` behavior:
+     - `None` => default input.
+     - explicit ID => selected if still input-capable.
+     - explicit invalid/missing ID => system default with `fallback_to_default = true`.
+   - Keep `start_recording_with_stream()` returning `InputDeviceSelection`.
+
+3. Wire app startup and picker state sync
+   - Refresh microphone list on startup and before user interaction via `refresh_input_devices()`.
+   - Keep `sync_input_device_name()` behavior so persisted names are repaired to current label when possible.
+   - Keep `selected_input_device_label()` as canonical display formatting.
+
+4. Implement picker UI behavior
+   - Keep `Refresh microphones` action tied to `refresh_input_devices()`.
+   - Keep combo options:
+     - `System default` mapped to `0`.
+     - discovered device ids mapped to list entries.
+   - On selection change:
+     - write `config.audio.input_device_id`.
+     - write `config.audio.input_device_name` for UI readability.
+     - call `persist_config()`.
+
+5. Apply startup-time fallback into recording flow
+   - In `start_recording()`, pass optional configured id using `configured_input_device_id()`.
+   - When `InputDeviceSelection` reports fallback:
+     - prepend fallback notice in status text.
+     - keep recorder + realtime session on fallback path.
+   - Continue to proceed with Pass2/Pass3 flow once recorder starts.
+
+6. Preserve diagnostics and constraints
+   - Keep user-facing status updates for:
+     - empty/failed refreshes,
+     - fallback-to-default behavior,
+     - non-macOS unsupported recording path.
+   - Keep behavior aligned with non-breaking UI contract and existing restart/reload behavior.
+
+## Validation scope (manual, no test rewrite)
+
+- Update docs/plans only; no code edits in this slice.
+- Verify the two key names are referenced as `audio.input_device_name` and `audio.input_device_id`.

docs/plans/2026-03-01-audio-input-device-selection-design.md

@@ -8,43 +8,42 @@ The split below is by question type, not by reader type.
 
 ## Primary taxonomy
 
+This repository standardizes on three primary documentation lanes:
+
 | Lane | Location | Answers | Holds |
 | --- | --- | --- | --- |
 | Spec | `docs/spec/` | What must be true? | Contracts, schemas, invariants, required behavior |
 | Runbook | `docs/runbook/` | Which sequence should I execute? | Operational procedures, onboarding steps, validation flows, recovery steps |
 | Reference | `docs/reference/` | How is it currently organized or implemented? | Repository layout, surface maps, current implementation boundaries |
-| Decisions | `docs/decisions/` | Why is it shaped this way? | Durable rationale, tradeoffs, and consequences |
+
+## Artifact lanes
+
+- `docs/plans/` is allowed for plan artifacts that are explicitly produced or consumed by
+  a planning workflow.
+- `docs/plans/` is not a primary documentation lane and is not authoritative for runtime
+  behavior, repository policy, or operator procedures.
 
 ## Placement rules
 
 - If a document defines correctness, it belongs in `docs/spec/`.
 - If a document defines operator actions, it belongs in `docs/runbook/`.
 - If a document describes current structure, ownership, or implementation boundaries, it
   belongs in `docs/reference/`.
-- If a document records durable rationale or tradeoffs, it belongs in
-  `docs/decisions/`.
-- If a document drifts across lanes, split it instead of stretching one file to answer
-  several question types.
 - Do not duplicate authoritative content across lanes. Link to the source of truth.
-- Do not add `docs/plans/` back. Transient planning artifacts are not part of the
-  durable docs tree in this repository.
 
 ## Naming rules
 
-- Directory names express document lane.
+- Directory names express document type.
 - File names express stable topic.
 - Use lowercase kebab-case for document file names.
-- Keep primary-lane file names short and topic-first.
-- Do not encode temporary versions such as `v1`, `draft2`, or dates into primary-lane
-  file names.
+- Do not encode temporary versions such as `v0`, `v1`, or `draft2` into stable file
+  names.
 - Do not repeat the directory class in the file name when the topic is already clear.
   Prefer `runtime.md` under `docs/spec/` over `runtime-spec.md`.
-- Prefer names like `runtime.md`, `first-run.md`, and `repository-layout.md`.
-- Keep `index.md` reserved for lane routers.
 
 ## Document headers
 
-Every primary-lane document should start with a short routing header.
+Every document should start with a short routing header.
 
 Spec header:
 
@@ -58,9 +57,9 @@ Runbook header:
 
 - `Goal`
 - `Read this when`
-- `Inputs` or `Preconditions`
+- `Preconditions` or `Inputs`
 - `Depends on`
-- `Outputs` or `Verification`
+- `Verification` or `Outputs`
 
 Reference header:
 
@@ -69,28 +68,18 @@ Reference header:
 - `Not this document`
 - `Covers`
 
-Decision header:
-
-- `Status`
-- `Date`
-- `Question`
-- `Decision`
-- `Consequences`
-
 ## Canonical entry points
 
 - Unified router: `docs/index.md`
 - Normative router: `docs/spec/index.md`
 - Procedural router: `docs/runbook/index.md`
 - Current-state router: `docs/reference/index.md`
-- Rationale router: `docs/decisions/index.md`
 - Repo task and automation entrypoints: `Makefile.toml`
 
 ## Update workflow
 
 - Behavior or schema change: update the relevant spec.
 - Procedure change: update the relevant runbook.
 - Structural or ownership change: update the relevant reference doc.
-- Tradeoff or rationale change: update the relevant decision doc.
-- If a document starts carrying normative content from another lane, move that content
-  into the authoritative lane and link to it.
+- If a document drifts across lanes, split it instead of stretching one document to do
+  several jobs.

docs/plans/2026-03-01-audio-input-device-selection.md

@@ -15,9 +15,9 @@ Question this index answers: "how is it currently organized or implemented?"
 
 - You need a normative contract.
 - You need an execution sequence or operator runbook.
-- You need durable design rationale rather than current-state description.
+- You need saved plan artifacts.
 
 ## Current reference docs
 
-- [`repository-layout.md`](./repository-layout.md) for the repository surface map and
+- [`workspace-layout.md`](./workspace-layout.md) for the repository surface map and
   directory ownership boundaries.

docs/policy.md

@@ -1,15 +1,14 @@
-# Repository Layout
+# Workspace Layout
 
 Purpose: Describe the current top-level repository surfaces and which concerns each one
 owns.
 
 Read this when: You need to know where the app entrypoint, shared packages, repo task
 definitions, or documentation topics currently live.
 
-Not this document: The normative runtime contract, the first-run operator sequence, or
-the design rationale behind specific product choices.
+Not this document: The normative runtime contract or the onboarding sequence.
 
-Covers: The repository surface map, ownership boundaries, and the role of `apps/`,
+Covers: The workspace surface map, ownership boundaries, and the role of `apps/`,
 `packages/`, `docs/`, `scripts/`, and repository root policy files.
 
 ## Top-level surfaces
@@ -23,7 +22,7 @@ Covers: The repository surface map, ownership boundaries, and the role of `apps/
 - `docs/spec/` holds normative runtime and behavior contracts.
 - `docs/runbook/` holds operator procedures such as onboarding and validation flows.
 - `docs/reference/` holds current repository and implementation surface maps.
-- `docs/decisions/` holds durable rationale and tradeoffs behind current design choices.
+- `docs/plans/` holds saved plan artifacts rather than governing repository policy.
 - `Makefile.toml` holds repo-native task names for lint, test, format, and checks.
 - `scripts/` holds repository helper scripts such as local macOS packaging helpers.
 - `.github/workflows/` holds CI and release automation.
@@ -32,8 +31,8 @@ Covers: The repository surface map, ownership boundaries, and the role of `apps/
 
 - Runtime authority stays in the application and package crates plus the governing specs
   under `docs/spec/`.
-- `docs/runbook/`, `docs/reference/`, and `docs/decisions/` must not override runtime
-  or configuration authority.
+- `docs/runbook/` and `docs/reference/` must not override runtime or configuration
+  authority.
 - `Makefile.toml` is the source of truth for named repository tasks.
-- Decision docs explain why the system is shaped a certain way; the spec still defines
-  what must be true at runtime.
+- `docs/plans/` can capture design or execution artifacts, but those files do not become
+  policy until their conclusions are promoted into spec, runbook, or reference docs.

docs/reference/index.md

@@ -1,4 +1,4 @@
-# First Run
+# First-Run Onboarding
 
 Goal: Bring a fresh macOS Voxit install to the point where sign-in, permissions, and
 paste work end to end.
@@ -69,7 +69,7 @@ $HOME/Library/Application Support/voxit/config.toml
 
 ## 6. Failure handling
 
-- If sign-in stalls, reopen the auth surface and retry with the visible-window path.
+- If sign-in stalls, reopen the auth surface and retry with the visible window path.
 - If a permission does not update, grant it in macOS System Settings and then re-check
   from Voxit.
 - If paste fails, verify Accessibility and Input Monitoring first before debugging the