# Seed Blueprint

Source: seed/seed.yml
Genomes: cli-interface [builtin], cli-nodejs [builtin], tui-client [builtin], cli-tui [builtin]

## Project Summary

- `metadata` [seed/seed.yml]
  name: cat-tui
  summary: A full-screen TUI that displays an ASCII cat.
  description: Defines generic TUI application guardrails for full-screen
    rendering, screens, keyboard navigation, focus, resize handling, and terminal
    restoration.


## Global Policies

- `security.no-secret-output` [builtin:cli-nodejs]
  description: Must not print environment variables, tokens, or credentials unless
    explicitly required by the Seed.


## Interfaces

- `interfaces.cli` [builtin:cli-nodejs]
  purpose: User invokes the project from a terminal as a Node.js CLI.
  examples:
    - node ./src/cli.js --help
    - <command> --help
  id: cli

- `interfaces.tui` [builtin:tui-client]
  purpose: User interacts with the project through a terminal user interface.
  examples:
    - run <command>
    - navigate with keyboard controls
  id: tui


## Functional Behavior

- `behavior.terminal-ui` [builtin:tui-client]
  description: The client presents an interactive terminal user interface.

- `behavior.keyboard-navigation` [builtin:tui-client]
  description: The TUI supports keyboard-driven navigation and actions.

- `behavior.tui-rendering` [builtin:cli-tui]
  full-screen-redraw: The interface renders and updates a coherent terminal
    viewport in place rather than emitting an ever-growing stream of output.
  stable-frame: Each completed render reflects one coherent application state
    without stale regions, interleaved output, or visibly partial frames.
  resize-redraw: Terminal resize events recompute layout and repaint the current
    screen without corrupting content or losing the active context.
  bounded-layout: Content is clipped, wrapped, scrolled, or otherwise adapted to
    the available viewport instead of drawing outside terminal bounds.
  id: tui-rendering

- `behavior.tui-rendering.full-screen-redraw` [builtin:cli-tui]
  description: The interface renders and updates a coherent terminal viewport in
    place rather than emitting an ever-growing stream of output.

- `behavior.tui-rendering.stable-frame` [builtin:cli-tui]
  description: Each completed render reflects one coherent application state
    without stale regions, interleaved output, or visibly partial frames.

- `behavior.tui-rendering.resize-redraw` [builtin:cli-tui]
  description: Terminal resize events recompute layout and repaint the current
    screen without corrupting content or losing the active context.

- `behavior.tui-rendering.bounded-layout` [builtin:cli-tui]
  description: Content is clipped, wrapped, scrolled, or otherwise adapted to the
    available viewport instead of drawing outside terminal bounds.

- `behavior.tui-screens` [builtin:cli-tui]
  explicit-screens: Distinct application contexts are modeled as identifiable
    screens, views, dialogs, or overlays with clear entry and exit behavior.
  current-context: The interface makes the current screen, active region, and
    available primary actions understandable to the user.
  transient-layers: Dialogs, menus, help, and error overlays preserve the
    underlying screen and return predictably when dismissed.
  id: tui-screens

- `behavior.tui-screens.explicit-screens` [builtin:cli-tui]
  description: Distinct application contexts are modeled as identifiable screens,
    views, dialogs, or overlays with clear entry and exit behavior.

- `behavior.tui-screens.current-context` [builtin:cli-tui]
  description: The interface makes the current screen, active region, and
    available primary actions understandable to the user.

- `behavior.tui-screens.transient-layers` [builtin:cli-tui]
  description: Dialogs, menus, help, and error overlays preserve the underlying
    screen and return predictably when dismissed.

- `behavior.tui-navigation` [builtin:cli-tui]
  keyboard-complete: Every primary workflow is operable from the keyboard.
  visible-focus: The currently focused interactive element or region is always
    visibly distinguishable.
  predictable-back: Back, cancel, and escape actions dismiss the nearest transient
    context or return to the previous screen without trapping focus.
  stable-controls: Navigation and action keys remain consistent across screens
    unless a screen clearly communicates a contextual override.
  discoverable-controls: The current screen exposes or provides access to help for
    its important navigation and action keys.
  id: tui-navigation

- `behavior.tui-navigation.keyboard-complete` [builtin:cli-tui]
  description: Every primary workflow is operable from the keyboard.

- `behavior.tui-navigation.visible-focus` [builtin:cli-tui]
  description: The currently focused interactive element or region is always
    visibly distinguishable.

- `behavior.tui-navigation.predictable-back` [builtin:cli-tui]
  description: Back, cancel, and escape actions dismiss the nearest transient
    context or return to the previous screen without trapping focus.

- `behavior.tui-navigation.stable-controls` [builtin:cli-tui]
  description: Navigation and action keys remain consistent across screens unless
    a screen clearly communicates a contextual override.

- `behavior.tui-navigation.discoverable-controls` [builtin:cli-tui]
  description: The current screen exposes or provides access to help for its
    important navigation and action keys.

- `behavior.tui-lifecycle` [builtin:cli-tui]
  managed-terminal-mode: Interactive terminal modes and full-screen presentation
    are entered only for the lifetime of the TUI session.
  restore-terminal: Normal exit, user cancellation, handled errors, and signals
    restore terminal modes, cursor visibility, and screen state before returning
    control to the shell.
  id: tui-lifecycle

- `behavior.tui-lifecycle.managed-terminal-mode` [builtin:cli-tui]
  description: Interactive terminal modes and full-screen presentation are entered
    only for the lifetime of the TUI session.

- `behavior.tui-lifecycle.restore-terminal` [builtin:cli-tui]
  description: Normal exit, user cancellation, handled errors, and signals restore
    terminal modes, cursor visibility, and screen state before returning control
    to the shell.

- `behavior.cat-screen` [seed/seed.yml]
  description: Enter a full-screen terminal view, render one centered ASCII cat,
    and keep it visible until the user quits.

- `behavior.quit` [seed/seed.yml]
  description: Pressing `q` or `Escape` exits and restores the terminal.


## Error Semantics

- `errors.non-interactive-terminal` [builtin:cli-tui]
  code: tui.non-interactive-terminal
  when: The full-screen interface is started without a usable interactive terminal.
  remediation: Fail visibly with a concise diagnostic or use an explicitly
    documented non-interactive interface; never emit broken control sequences.
  id: non-interactive-terminal

- `errors.terminal-capability-failure` [builtin:cli-tui]
  code: tui.terminal-capability-failure
  when: Required terminal capabilities cannot be initialized or maintained.
  remediation: Restore any changed terminal state and fail visibly with a concise diagnostic.
  id: terminal-capability-failure

- `errors.unsupported-terminal` [seed/seed.yml]
  description: If a full-screen TUI cannot be opened, print a clear error and exit
    nonzero without corrupting the terminal.


## Security

- `security.no-secret-output` [builtin:cli-nodejs]
  description: Must not print environment variables, tokens, or credentials unless
    explicitly required by the Seed.


## Environment

- `environment.node-runtime` [builtin:cli-nodejs]
  description: Must run on Node.js 20 or newer.

- `environment.npm-install` [builtin:cli-nodejs]
  description: Dependencies are installed with npm from package.json and
    package-lock.json when present.

- `environment.linux` [builtin:cli-nodejs]
  description: Must run on Linux shells.

- `environment.terminal` [builtin:tui-client]
  description: The client runs in a terminal environment with documented terminal
    capability assumptions.


## Observability

- `observability.stderr-errors` [builtin:cli-interface]
  description: User-facing errors must be written to stderr.

- `observability.exit-codes` [builtin:cli-interface]
  description: Exit code 0 means success; nonzero means validation, input, or
    execution failure.


## Compatibility

- `compatibility.terminal-cleanup` [builtin:cli-tui]
  description: Returning to the shell must not leave raw input mode, hidden cursor
    state, corrupted terminal attributes, or TUI rendering artifacts.


## Constraints

- `constraints.nodejs-cli-runtime` [builtin:cli-nodejs]
  description: The implementation is a Node.js command line application.

- `constraints.terminal-user-interface` [builtin:tui-client]
  description: The target project exposes a terminal user interface client.

- `constraints.full-screen-terminal-application` [builtin:cli-tui]
  description: The target interface behaves as an interactive terminal application
    comparable to nano, Vim, or htop, not as a line-oriented script that
    repeatedly prints replacement output.

- `constraints.no-framework-requirement` [builtin:cli-tui]
  description: This genome imposes behavior and interaction contracts only; it
    does not require a TUI framework, rendering library, or architecture.


## Implementation Freedom

- `freedom.nodejs-cli-structure` [builtin:cli-nodejs]
  description: Implementation may choose any maintainable internal Node.js module structure.

- `freedom.tui-framework` [builtin:cli-tui]
  description: The implementation may choose any framework, terminal library,
    rendering strategy, state model, and screen architecture that satisfies the
    observable TUI contract.


## Verification Plan

- `verifications.tui-application-lifecycle` [builtin:cli-tui]
  title: Full-screen TUI lifecycle is safe
  description: Verify the interface redraws in place and restores the terminal
    after normal exit and an interrupted or failed session.
  method: Exercise the TUI in a pseudo-terminal, navigate between screens, resize
    it, exit normally, interrupt a second run, and inspect terminal state.
  evidence_required:
    - Pseudo-terminal command or harness used.
    - Screen navigation and resize observations.
    - Terminal state observations after normal and interrupted exit.
  id: tui-application-lifecycle

- `verifications.tui-keyboard-navigation` [builtin:cli-tui]
  title: Keyboard navigation is complete and visible
  description: Verify primary screens and actions are reachable with visible
    focus, discoverable controls, and predictable back or cancel behavior.
  method: Exercise every primary workflow using only documented keyboard controls.
  evidence_required:
    - Screens and primary workflows exercised.
    - Navigation and action keys used.
    - Focus, help, back, and cancel behavior observed.
  id: tui-keyboard-navigation
