feat(help): route contextual command rows to shared explainers

.agent/handoffs/task-43.4.txt

@@ -0,0 +1,32 @@
+Title: Split Cross-Cutting Operator Semantics from Local Context Pages
+Acceptance target: Contextual F1 pages stay task-local, shared operator semantics are reachable through real runtime follow paths, help-popup navigation is distinct from runtime navigation, and focused help regressions validate the final open/follow/back/close hint-line workflow.
+Completion objective: Make Task 43.4 true end-to-end across authored help sources, generated runtime topic data, help-popup/runtime follow behavior, and focused help tests, while including the already-edited roadmap/spec source-of-truth updates in the same commit.
+
+Chosen work family: Runtime contextual-row follow ownership + shared-topic cleanup + focused help workflow tests.
+Deferred families: None. Task 43.2 and Idea FE-7 remain explicitly out of scope for this mission.
+
+Inventory
+- docs/ROADMAP.md — source-of-truth roadmap wording already edited locally; include in this commit. [addressed]
+- docs/SPECIFICATION.md — source-of-truth contract wording already edited locally; include in this commit. [addressed]
+- etc/help/f1.en.md — authored contextual/runtime help ownership, shared-topic routing, local-page slimming. [addressed]
+- etc/help/f1.de.md — topic inventory/schema parity for shared-topic additions. [addressed]
+- etc/help/man.en.md — topic inventory/schema parity for generated usage/man outputs. [addressed]
+- docs/USAGE.md — generated from man help source; regenerated for parity. [addressed]
+- etc/ytnova.1.md — generated from man help source; regenerated for parity. [addressed]
+- scripts/generate_help_assets.py — support-topic ordering updated for new shared topics. [addressed]
+- src/core/generated_help_topics.h — regenerated runtime topic data. [addressed]
+- src/ui/runtime_help.c — contextual row follow wiring, shared-topic ownership lookup, footer hint/navigation behavior. [addressed]
+- src/ui/help_popup.c — existing footer rendering/viewport behavior already satisfied the contract; no code change required. [intentionally unchanged]
+- tests/test_help_source_schema.py — shared-topic inventory/schema parity. [addressed]
+- tests/test_help_generator.py — generator/runtime header expectations for new shared topics. [addressed]
+- tests/test_help_text_contract.py — focused live help popup workflow/discoverability coverage updated for shared-topic follow semantics and new hint-line behavior. [addressed]
+
+Validation
+- `make help-assets`
+- `make clean && make`
+- `source .venv/bin/activate && pytest -q tests/test_help_source_schema.py tests/test_help_generator.py tests/test_help_text_contract.py`
+
+Result
+- Shared operator semantics now live in shared topics with real follow paths from contextual command rows.
+- Contextual pages keep task-local key ownership while shared topics carry cross-cutting destination/jump semantics.
+- Focused help tests now validate follow/back behavior without preserving the pre-43.4 inline-detail assumptions.

docs/ROADMAP.md

@@ -851,6 +851,7 @@ Ordering policy (for all editors, including AI editors):
 *   **Goal:** Define and implement distinct theme-role behavior for the contextual `F1` reading surface and the always-visible footer guidance surface now that the base role-based theme system exists.
 *   **Rationale:** Task 60 established the general theme architecture, but it intentionally left `help` overloaded across the footer and the `F1` reading surface. Contextual help now needs its own follow-on theming pass so the reading surface, linked text, and active linked target remain readable, restrained, and consistent across bundled themes while the footer keeps an independently tunable low-noise scheme.
 *   **Theme Contract:** All footer and `F1` visual styling belongs in `etc/ytnova.themes` / runtime theme data, not `ytnova.conf`. Reserve `help` for the `F1` reading surface, introduce a dedicated `footer` role for the footer keybinding strip, and allow narrower roles such as `help_link` and `help_link_selection` if hyperlink help needs them. Prompt/dialog surfaces remain separate concerns unless a later task explicitly gives them their own theme role.
+*   **Scope Limit:** This task owns only surface-level/help-UI roles such as body text, footer strip, frame lines, link text, active link emphasis, and help-popup mnemonic emphasis. It does **not** own optional semantic per-span styling inside help prose; richer intra-text emphasis such as headings, commands, notes, or warnings is deferred to Idea FE-7 after the content/IA settles.
 *   **Orthodox Default Direction:** Keep the help page readable and quiet on the orthodox-blue theme: black-on-grey body text, black-on-cyan linked text, and yellow-on-cyan active-link emphasis are acceptable; ordinary body text must remain easier to read than navigation chrome.
 *   The footer should remain concise and lower-noise than modal help while still allowing its own color treatment.
 *   **Acceptance Criteria:**
@@ -888,7 +889,9 @@ Ordering policy (for all editors, including AI editors):
 *   **Goal:** Make contextual `F1` pages answer the immediate screen/prompt question first, while shared operator semantics live in dedicated explainer topics that can be reused across multiple surfaces.
 *   **Rationale:** The current failure mode is not just missing prose; it is information-architecture blur. When local command summaries, shared rules, help-popup navigation, and reference-detail all compete on the same page, `F1` feels noisy and unreliable even when the facts are present. Users need a crisp distinction between "what this screen does now," "how this repeated ytnova feature family works in general," and "where the full reference lives."
 *   **Comprehensiveness Contract:** A user pressing `F1` on any supported surface must be able to reach an answer for the active question without being stranded by omissions. If the first contextual page is intentionally short, it must still provide an obvious path to the owning shared topic or command explainer rather than silently assuming outside knowledge.
+*   **Unix Documentation Principle:** ytnova should follow the Unix split between short in-app help and fuller external reference. `F1` is the contextual task-local path, while exhaustive semantics/configuration detail remain the job of the manpage and generated usage/reference docs. Centralized authored help sources are acceptable for maintenance, but the runtime popup must still present only small contextual slices rather than a giant manual.
 *   **Scope Contract:** Treat repeated operator rules as first-class shared topics rather than smearing partial explanations across directory/file/archive/F7/F8/Showall/Global/prompt pages. The shared inventory must be broad enough to cover the recurrent question families users actually ask, including filters, jump/list-jump behavior, wildcard and rename-pattern rules, search/fuzzy-matching semantics, command-line editing, `VI_KEYS=1`, theming/customization, tagged-set semantics, compare/output syntax families, and operator-facing tips/tricks where they truly generalize.
+*   **Implementation Reality Contract:** This task is not text-only. It owns the runtime/help-popup behavior needed to make the authored IA real: contextual command rows must be able to open their owning shared topic or command explainer instead of trapping the user in local inline detail only, and the focused regression tests must be updated to validate the intended workflow rather than preserving the older limited model by accident.
 *   **Navigation Taxonomy Contract:** Explicitly separate **help-popup navigation** (`Up`/`Down`, `PgUp`/`PgDn`, `Home`/`End`, `Enter`/`Right`, `Left`, `Esc`/`Q`) from **runtime ytnova navigation** (tree/file movement, jump, prompts, split movement, preview movement, tagged flows, etc.). `F1` must not blur those two domains together on the same first-screen explanation.
 *   **Page-Shape Contract:** Each contextual page should answer, in order: where the user is, the main actions available here, the few caveats/traps specific to this surface, and which shared topic explains the deeper rule. Shared topics may then teach the reusable semantics once, with concise examples, without forcing every local page to repeat them.
 *   **Hint-Line Contract:** The help-popup hint line may expand beyond the current minimal trio when needed to keep the shared-topic structure discoverable, but it must remain low-noise and semantically honest. If Back, Contents, Navigation, list/detail switching, or other cross-topic movement is part of the intended help workflow, the hint line must advertise enough of that workflow that the user is not expected to guess it.
@@ -902,6 +905,9 @@ Ordering policy (for all editors, including AI editors):
 *   When tags change a command's behavior, the local command page explains that tagged variant inline for the current surface instead of relying on the shared Tagged topic as the only explanation path.
 *   The shared-topic inventory is reviewed as an explicit user-question matrix rather than as an author-memory list, so missing recurrent questions are tracked as coverage defects.
 *   The help-popup hint line is validated against the final IA: it remains concise, but it is expanded where necessary so the new structure is discoverable without hidden gestures.
+*   Contextual command rows that need deeper explanation have a real follow path at runtime to the owning shared topic or command explainer; authored `topic:` links are not allowed to exist only on paper while the popup remains trapped in local inline detail.
+*   Shared semantics with multiple current owners are reconciled to one owning topic family. At minimum, split-model rules, wildcard/rename-target rules, jump/list-jump semantics, and search/filter semantics are not maintained independently across every local mode page.
+*   Regression tests stop hard-coding the pre-43.4 discoverability model. Focused help tests must validate the chosen open/follow/back/close workflow and the final hint-line affordances instead of asserting the old minimal trio when the new IA requires more explicit cues.
 *   Any "tips and tricks" guidance admitted into `F1` is curated as reusable operator guidance rather than leaking one-off editorial advice into arbitrary local pages.
 *   - [ ] **Status:** Not Started.
 
@@ -1558,12 +1564,13 @@ Ordering policy (for all editors, including AI editors):
 
 ### **Idea FE-7: Semantic F1 Help Styling Without Theme Bloat**
 *   **Goal:** Allow authored `F1` help topics to request a small bounded set of semantic text styles while keeping `ytnova.themes` compact and stable.
+*   **Dependency/Sequencing Note:** Evaluate this only after Task 43.4 has stabilized the help information architecture/content shape and Task 43.2 has settled the base help/footer surface-role contract. FE-7 is a follow-on enhancement for proven emphasis needs, not a prerequisite for making `F1` useful.
 *   **Design Direction:**
     *   Use semantic markup roles in `etc/help/f1.en.md` rather than raw color/attribute requests.
     *   Initial role set should stay intentionally small (for example `help_text`, `help_key`, `help_code`, `help_heading`, `help_note`, `help_warning`).
     *   `ytnova.themes` maps those semantic roles to ncurses-supported attributes/colors.
     *   Missing theme entries must fall back deterministically to the normal help-text style.
-*   **Non-Goal:** Do not allow arbitrary per-span foreground/background pairs or unlimited raw `bold`/`inverse`/`underline` directives directly in help source; that would balloon theme surface area and couple authored help text to presentation internals.
+*   **Non-Goal:** Do not allow arbitrary per-span foreground/background pairs or unlimited raw `bold`/`inverse`/`underline` directives directly in help source; that would balloon theme surface area and couple authored help text to presentation internals. FE-7 does not replace Task 43.2's surface-role ownership; it only adds a bounded semantic layer within already-settled help surfaces.
 *   **Rationale:** Users may want richer help emphasis, but the safe path is a bounded semantic layer so help authors describe meaning and the theme decides appearance.
 *   - [ ] **Status:** Not Started.
 

docs/SPECIFICATION.md

@@ -348,6 +348,7 @@ A bordered pop-up box that overlays the center of the screen, used for:
 ### 6.4 Context Help Contract (Footer <-> F1)
 *   **Parity Rule:** For any active context, commands shown in the footer keybinding hints MUST appear in that context's F1 help set. Missing footer commands in F1 are defects.
 *   **Concision Rule:** F1 content is concise, contextual, and beginner-friendly. The help popup teaches the active surface in plain English; terse reference-style detail belongs in the manpage source and generated `docs/USAGE.md`.
+*   **Unix Documentation Layering Rule:** ytnova follows the Unix split between in-app help and full reference. `F1` is the short contextual path for the active task, `--help`/usage stays terse, and the manpage/reference docs own exhaustive behavior and configuration detail. A single maintained authored help corpus is allowed internally, but runtime `F1` MUST render only small contextual slices rather than presenting one giant browsing document.
 *   **Answerability Rule:** Pressing `F1` on any covered surface MUST leave the user with an answer path. The answer may be present on the opening contextual page or on one clearly signposted help-popup link hop to the owning explainer/shared topic, but the user must not be stranded by omitted semantics or hidden structure.
 *   **Surface Naming Rule:** Keep the four help surfaces distinct in docs, tests, and code comments: the always-visible bottom-of-screen strip is the **footer command strip**; the modal opened by `F1` is the **help popup**; the minimal action row embedded in that popup is the **help-popup hint line**; and any command/topic entry that exists specifically to branch into deeper explanation is a **help popup link**.
 *   **Help-Family Rule:** Keep three authored help families distinct. **Contextual pages** belong to one active runtime surface (mode, prompt, dialog, picker, preview, split, or future equivalent). **Command explainers** belong to one command or concept family such as Copy, Filter, Compare, Output, Jump, or wildcard rename semantics. **Shared topics** belong to cross-cutting behavior such as help navigation, tagged workflow, command-line editing, VI keys, theming/customization, search semantics, or command catalogs.

docs/USAGE.md

@@ -371,6 +371,28 @@ Then choose the final destination.
 * **Up**: Open or cycle prompt history when that prompt keeps history.
 * **F2**: Open a browser or picker when the current prompt supports browsing.
 * **F1**: Show syntax or scope rules that matter only to the current prompt.
+### Copy/Move Targets
+
+#### Target forms
+Use a directory path when you want the original names preserved under another directory.
+Use one full replacement name when you want one selected item to land under a new explicit name.
+Use a wildcard pattern such as `*.bak` or `copy-*` when you want ytnova to rewrite each selected basename by pattern.
+
+#### Shared rules
+Tagged copy/move uses the same target syntax as single-item copy/move.
+Split mode may seed the inactive-panel directory as the default target, but you can still replace that default before the operation starts.
+Archive-backed copy/move keeps the same destination model even when extraction or archive-aware paths are involved.
+### List Jump
+
+#### Jump model
+`/` opens an incremental jump prompt for the current visible list only.
+Tree/directory views jump among visible directory names, while file-oriented views jump among the visible file rows for that surface.
+
+#### Acceptance and cancel
+* **Type text**: Move immediately to the best current match as you type.
+* **Enter**: Keep the current match and stay there.
+* **Esc**: Cancel the jump and restore the original selection.
+* **Scope changes**: Filtering, Showall/Global projection, archives, and split mode all change which visible list `/` searches, but they do not change the jump keys themselves.
 ### VI Keys
 
 #### Navigation remap