docs: simplify getting started, trim cookbook, update docs for removed instructions primitive and new prompt resolution

Remove instructions primitive references across all docs and tests.
Replace -p/--prompt and -f/--ralph-file CLI flags with a single smart
positional [PROMPT] argument. Trim getting-started (remove Claude Code
install, pipx/pip tabs, tips section) and cookbook (keep only docs and
coverage recipes). Closes #10.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: 2 people

docs/cli.md

@@ -83,8 +83,8 @@ Start the autonomous coding loop.
 ralph run                          # Run forever (Ctrl+C to stop)
 ralph run docs                     # Use the "docs" named ralph
 ralph run -n 5                     # Run 5 iterations
-ralph run -p "Fix the login bug"   # Ad-hoc prompt (no RALPH.md needed)
-ralph run -f path/to/prompt.md     # Use a specific prompt file
+ralph run "Fix the login bug"      # Ad-hoc inline prompt
+ralph run path/to/prompt.md        # Use a specific prompt file
 ralph run --stop-on-error          # Stop if agent exits non-zero
 ralph run --delay 10               # Wait 10s between iterations
 ralph run --timeout 300            # Kill agent after 5 minutes per iteration
@@ -93,16 +93,21 @@ ralph run --log-dir ralph_logs     # Save output to log files
 
 | Argument / Option | Short | Default | Description |
 |---|---|---|---|
-| `[RALPH_NAME]` | | none | Name of a [named ralph](primitives.md#ralphs) in `.ralphify/ralphs/` |
+| `[PROMPT]` | | none | Ralph name, file path, or inline prompt text (see resolution below) |
 | `-n` | | unlimited | Max number of iterations |
-| `--prompt` | `-p` | none | Ad-hoc prompt text. Overrides the ralph file |
-| `--ralph-file` | `-f` | none | Path to a ralph file. Overrides `ralph.toml` |
 | `--stop-on-error` | `-s` | off | Stop loop if agent exits non-zero or times out |
 | `--delay` | `-d` | `0` | Seconds to wait between iterations |
 | `--timeout` | `-t` | none | Max seconds per iteration |
 | `--log-dir` | `-l` | none | Directory for iteration log files |
 
-Ad-hoc prompts (`-p`) still resolve context and instruction placeholders. When `-p` is provided, `RALPH.md` doesn't need to exist.
+The `[PROMPT]` argument is smart — it resolves in order:
+
+1. If it matches a named ralph in `.ralphify/ralphs/` → use that ralph
+2. If it's an existing file path → use as prompt file
+3. Otherwise → treat as inline prompt text
+4. If omitted → fall back to `ralph.toml` `agent.ralph`
+
+Inline prompts still resolve context placeholders. When inline text is provided, `RALPH.md` doesn't need to exist.
 
 ### `ralph status`
 
@@ -116,7 +121,7 @@ This command checks:
 
 - Whether the prompt file exists
 - Whether the agent command is on PATH
-- All discovered checks, contexts, instructions, and named ralphs (with enabled/disabled status)
+- All discovered checks, contexts, and named ralphs (with enabled/disabled status)
 
 If everything is configured correctly, it prints "Ready to run." If not, it tells you exactly what's wrong.
 
@@ -126,19 +131,17 @@ Scaffold new primitives. Each command creates a directory under `.ralphify/` wit
 
 ```bash
 ralph new check <name>         # Create .ralphify/checks/<name>/CHECK.md
-ralph new instruction <name>   # Create .ralphify/instructions/<name>/INSTRUCTION.md
 ralph new context <name>       # Create .ralphify/contexts/<name>/CONTEXT.md
 ralph new ralph <name>         # Create .ralphify/ralphs/<name>/RALPH.md
 ```
 
 #### Ralph-scoped primitives
 
-Checks, contexts, and instructions accept a `--ralph` option to create them inside a named ralph's directory. These [ralph-scoped primitives](primitives.md#ralph-scoped-primitives) only apply when running that specific ralph.
+Checks and contexts accept a `--ralph` option to create them inside a named ralph's directory. These [ralph-scoped primitives](primitives.md#ralph-scoped-primitives) only apply when running that specific ralph.
 
 ```bash
 ralph new check docs-build --ralph docs        # .ralphify/ralphs/docs/checks/docs-build/CHECK.md
 ralph new context doc-coverage --ralph docs     # .ralphify/ralphs/docs/contexts/doc-coverage/CONTEXT.md
-ralph new instruction writing-style --ralph docs  # .ralphify/ralphs/docs/instructions/writing-style/INSTRUCTION.md
 ```
 
 | Option | Description |

docs/contributing/codebase-map.md

@@ -10,7 +10,7 @@ Quick orientation guide for anyone working on this codebase — human contributo
 
 Ralphify is a CLI tool (`ralph`) that runs AI coding agents in autonomous loops. It reads a prompt file, pipes it to an agent command (e.g. `claude -p`), waits for it to finish, then repeats. Each iteration gets a fresh context window. Progress is tracked through git commits.
 
-The core loop is simple. The complexity lives in **prompt assembly** — resolving contexts, instructions, and check failures into the prompt before each iteration.
+The core loop is simple. The complexity lives in **prompt assembly** — resolving contexts and check failures into the prompt before each iteration.
 
 ## Directory structure
 
@@ -22,9 +22,8 @@ src/ralphify/           # All source code
 ├── manager.py          # Multi-run orchestration (concurrent runs via threads)
 ├── checks.py           # Discover and run validation checks, format failures
 ├── contexts.py         # Discover and run dynamic data contexts, resolve into prompt
-├── instructions.py     # Discover and resolve static text instructions
 ├── ralphs.py           # Named ralph discovery and resolution (resolve_ralph_source)
-├── resolver.py         # Template placeholder resolution (shared by contexts + instructions)
+├── resolver.py         # Template placeholder resolution (used by contexts)
 ├── detector.py         # Auto-detect project type from manifest files
 ├── _agent.py           # Run agent subprocesses (streaming + blocking modes, log writing)
 ├── _run_types.py       # RunConfig, RunState, RunStatus — shared data types for the engine
@@ -54,15 +53,14 @@ ralph run
   │
   ├── cli.py:run() — parse options, print banner
   │   ├── Load config from ralph.toml
-  │   ├── Resolve prompt via ralphs.resolve_ralph_source() (--prompt > name > --ralph-file > toml > root)
+  │   ├── Resolve prompt via ralphs.resolve_ralph_source() (name > file path > inline text > toml)
   │   └── Build RunConfig and call engine.run_loop()
   │
   └── engine.py:run_loop(config, state, emitter)
-       ├── Discover checks, contexts, instructions from .ralphify/
+       ├── Discover checks, contexts from .ralphify/
        └── Loop:
             ├── Read RALPH.md (or use ad-hoc text)
             ├── Run contexts → resolve {{ contexts.* }} placeholders
-            ├── Resolve {{ instructions.* }} placeholders
             ├── Append check failures from previous iteration (if any)
             ├── Pipe assembled prompt to agent command via subprocess
             ├── Emit iteration events (started, completed, failed, timed_out)
@@ -71,25 +69,24 @@ ralph run
             └── Repeat
 ```
 
-### The four primitives and the `Primitive` protocol
+### The three primitives and the `Primitive` protocol
 
-All four primitive types follow the same pattern: a directory under `.ralphify/` with a marker markdown file containing YAML frontmatter. Each type's dataclass (`Check`, `Context`, `Instruction`, `Ralph`) satisfies the `Primitive` protocol defined in `_discovery.py`, which requires `name` and `enabled` properties. This enables type-safe generic functions for discovery, filtering, merging, and display — the engine's `_discover_and_filter_enabled()` helper uses the protocol to handle all four types through a single code path.
+All three primitive types follow the same pattern: a directory under `.ralphify/` with a marker markdown file containing YAML frontmatter. Each type's dataclass (`Check`, `Context`, `Ralph`) satisfies the `Primitive` protocol defined in `_discovery.py`, which requires `name` and `enabled` properties. This enables type-safe generic functions for discovery, filtering, merging, and display — the engine's `_discover_and_filter_enabled()` helper uses the protocol to handle all three types through a single code path.
 
 | Primitive | Marker file | Runs | Injects into prompt |
 |---|---|---|---|
 | Check | `CHECK.md` | After iteration | Failures appended to next prompt |
 | Context | `CONTEXT.md` | Before iteration | Output replaces `{{ contexts.name }}` |
-| Instruction | `INSTRUCTION.md` | Before iteration | Content replaces `{{ instructions.name }}` |
 | Ralph | `RALPH.md` | At run start | Replaces root RALPH.md when selected by name |
 
 Discovery is handled by `_discovery.py:discover_primitives()` which scans `.ralphify/{kind}/*/` for marker files. The engine groups enabled primitives into an `EnabledPrimitives` NamedTuple for clean parameter passing.
 
 ### Placeholder resolution
 
-Both contexts and instructions use the same resolver (`resolver.py:resolve_placeholders()`):
+Contexts use the resolver (`resolver.py:resolve_placeholders()`):
 
-- `{{ contexts.git-log }}` — named placement for a specific primitive
-- `{{ contexts }}` — bulk placement for all remaining primitives
+- `{{ contexts.git-log }}` — named placement for a specific context
+- `{{ contexts }}` — bulk placement for all remaining contexts
 - No placeholders at all — everything appended to the end of the prompt
 
 ### Event system
@@ -117,14 +114,14 @@ The CLI uses a `ConsoleEmitter` (defined in `_console_emitter.py`) that renders
 1. **`engine.py`** — The core run loop. Uses `RunConfig` and `RunState` (from `_run_types.py`) and `EventEmitter`. This is where iteration logic lives.
 2. **`_run_types.py`** — `RunConfig`, `RunState`, and `RunStatus`. These are the shared data types used by the engine, CLI, and manager. Separated so modules that only need the types don't pull in execution logic.
 3. **`cli.py`** — All CLI commands. Delegates to `engine.run_loop()` for the actual loop. Prompt source resolution (name vs. file path vs. inline) lives in `ralphs.py:resolve_ralph_source()`. Scaffold templates live in `_templates.py`. Terminal event rendering lives in `_console_emitter.py`.
-4. **`_frontmatter.py`** + **`_discovery.py`** — Frontmatter parsing and primitive discovery. `_frontmatter.py` handles YAML parsing and defines marker constants. `_discovery.py` defines the `Primitive` protocol, scans `.ralphify/` directories, and provides `merge_by_name()` for overlaying ralph-scoped primitives on globals. Understanding both is essential for working on checks/contexts/instructions/ralphs.
-5. **`resolver.py`** — Template placeholder logic shared by contexts and instructions. Small file but critical — changes here affect both.
+4. **`_frontmatter.py`** + **`_discovery.py`** — Frontmatter parsing and primitive discovery. `_frontmatter.py` handles YAML parsing and defines marker constants. `_discovery.py` defines the `Primitive` protocol, scans `.ralphify/` directories, and provides `merge_by_name()` for overlaying ralph-scoped primitives on globals. Understanding both is essential for working on checks/contexts/ralphs.
+5. **`resolver.py`** — Template placeholder logic used by contexts. Small file but critical.
 
 ## Traps and gotchas
 
 ### If you change the primitive marker filenames...
 
-The marker file names (`CHECK.md`, `CONTEXT.md`, `INSTRUCTION.md`, `RALPH.md`) are defined as constants in `_frontmatter.py` (`CHECK_MARKER`, `CONTEXT_MARKER`, `INSTRUCTION_MARKER`, `RALPH_MARKER`). The primitives directory name is `PRIMITIVES_DIR`. All modules — `checks.py`, `contexts.py`, `instructions.py`, `ralphs.py`, and `cli.py` — import from there. Change the constant to rename everywhere.
+The marker file names (`CHECK.md`, `CONTEXT.md`, `RALPH.md`) are defined as constants in `_frontmatter.py` (`CHECK_MARKER`, `CONTEXT_MARKER`, `RALPH_MARKER`). The primitives directory name is `PRIMITIVES_DIR`. All modules — `checks.py`, `contexts.py`, `ralphs.py`, and `cli.py` — import from there. Change the constant to rename everywhere.
 
 ### If you change frontmatter fields...