docs: add prompt resolution priority chain to How It Works so users understand the full prompt flow

The How It Works page explained prompt *assembly* (contexts, instructions,
check failures) but didn't explain prompt *resolution* — how ralphify decides
which prompt to use when multiple sources are available (-p flag, named
prompts, --prompt-file, ralph.toml, fallback PROMPT.md). Added a priority
chain table between the assembly diagram and the context resolution section.

Also fixed the project detection order in cli.md to match the actual code
(package.json is checked before pyproject.toml).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: 2 people

docs/cli.md

@@ -117,7 +117,7 @@ ralph init --force   # Overwrite existing files
 |---|---|---|---|
 | `--force` | `-f` | off | Overwrite existing `ralph.toml` and `PROMPT.md` |
 
-During init, ralphify detects your project type by looking for manifest files (`pyproject.toml`, `package.json`, `Cargo.toml`, `go.mod`). The detected type is displayed but doesn't currently change the generated configuration — all project types get the same defaults.
+During init, ralphify detects your project type by looking for manifest files (`package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`). The detected type is displayed but doesn't currently change the generated configuration — all project types get the same defaults.
 
 ### `ralph run`
 

docs/how-it-works.md

@@ -88,6 +88,18 @@ flowchart LR
     style I fill:#00897b,color:#fff
 ```
 
+But first — where does the prompt come from? Ralphify resolves the prompt source using a priority chain. The first match wins:
+
+| Priority | Source | How to use |
+|---|---|---|
+| 1 | `-p` flag | `ralph run -p "Fix the login bug"` — inline ad-hoc text |
+| 2 | Positional name | `ralph run docs` — looks up `.ralph/prompts/docs/PROMPT.md` |
+| 3 | `-f` / `--prompt-file` flag | `ralph run -f path/to/prompt.md` — explicit file path |
+| 4 | `ralph.toml` `prompt` field | Can be a [named prompt](primitives.md#prompts) or a file path |
+| 5 | Fallback | `PROMPT.md` in the project root |
+
+Once the prompt text is loaded, the three assembly layers run in order:
+
 ### 1. Context resolution
 
 For each enabled context, ralphify runs its command (if it has one) and combines the static content with the command output. Then it resolves placeholders in the prompt: