Sync documentation

Author: jedisct1

docs.md/audit.md

@@ -5,7 +5,7 @@ The `/audit` command runs a multi-phase security audit over committed Git-tracke
 It triages files by attack surface, performs deep review on escalated files, verifies each finding with an isolated proof-of-concept agent, generates patches, and writes structured reports. Only provable bugs survive to the final output.
 
 ```text
-/audit [path|glob ...] [--resume] [--regen] [--workers N]
+/audit [path|glob ...] [--resume] [--regen] [--workers N] [--debug]
 ```
 
 Works in both interactive (REPL) and one-shot mode (requires `--oneshot-commands`). Runs against `HEAD`, so dirty working-directory changes are ignored.
@@ -154,6 +154,12 @@ swival> /audit --regen
 swival> /audit --workers 8
 ```
 
+`--debug` writes a real-time JSONL trace of every audit step to `.swival/audit/debug.jsonl`. Useful when investigating a stuck phase, a missing finding, or unexpected resume behavior.
+
+```text
+swival> /audit --debug
+```
+
 All options can be combined with a focus path:
 
 ```text

docs.md/python-api.md

@@ -84,7 +84,6 @@ Session(
     lifecycle_fail_closed: bool = False,
     lifecycle_enabled: bool = True,
     command_middleware: str | None = None,
-    aws_profile: str | None = None,
     approved_buckets: set[str] | None = None,
 )
 ```

docs.md/tools.md

@@ -137,7 +137,7 @@ Calling `save` before `restore` is not required. The system automatically create
 
 ### Dirty Scopes
 
-Tools are classified as read-only or mutating. Read-only tools (`read_file`, `read_multiple_files`, `list_files`, `grep`, `fetch_url`, `view_image`, `think`, `todo`, `snapshot`) are safe to collapse because they don't change anything on disk. Mutating tools (`write_file`, `edit_file`, `delete_file`, `run_command`, unknown MCP tools, and A2A tools) dirty the scope.
+Tools are classified as read-only or mutating. Read-only tools (`read_file`, `read_multiple_files`, `list_files`, `grep`, `outline`, `fetch_url`, `view_image`, `think`, `todo`, `snapshot`) are safe to collapse because they don't change anything on disk. Mutating tools (`write_file`, `edit_file`, `delete_file`, `run_command`, unknown MCP tools, and A2A tools) dirty the scope.
 
 If the scope contains mutating tool calls, `restore` fails with a list of the dirty tools. Pass `force=true` to override when you are confident the summary captures the mutations.
 
@@ -217,11 +217,11 @@ The session goal is wiped by `/clear`. Goals are not persisted across processes;
 
 The `/goal` slash command exposes the same state to the user:
 
-| Command | Effect |
-|---|---|
-| `/goal` | Show current goal status, or "No goal is currently set." |
-| `/goal <objective>` | Create a goal (refused if one already exists). |
-| `/goal replace <objective>` | Replace the existing goal and reset counters. |
-| `/goal pause` | Pause the active goal. |
-| `/goal resume` | Resume a paused goal. |
-| `/goal clear` | Remove the current goal. |
+| Command                     | Effect                                                   |
+| --------------------------- | -------------------------------------------------------- |
+| `/goal`                     | Show current goal status, or "No goal is currently set." |
+| `/goal <objective>`         | Create a goal (refused if one already exists).           |
+| `/goal replace <objective>` | Replace the existing goal and reset counters.            |
+| `/goal pause`               | Pause the active goal.                                   |
+| `/goal resume`              | Resume a paused goal.                                    |
+| `/goal clear`               | Remove the current goal.                                 |

docs.md/usage.md

@@ -76,11 +76,13 @@ Without `--oneshot-commands`, input that looks like a command script is treated
 
 `/extend` doubles the current turn budget. `/extend <N>` sets the turn budget to an exact value.
 
+`/goal` manages a persisted thread goal. With no argument, it prints the current goal status. `/goal <objective>` creates a goal and immediately starts the agent loop on it; the runtime then keeps issuing continuation prompts after each final answer until the model calls `complete_goal`, the goal is paused or cleared, or `--max-turns` is hit. `/goal replace <objective>` swaps in a new objective and resets the counters. `/goal pause`, `/goal resume`, and `/goal clear` adjust state without starting a turn. The set/replace forms are REPL-only — they refuse in one-shot mode because v1 has no slash syntax for the token budget required for unattended runs. See [Goal Tool](tools.md#goal-tool-complete_goal) for the full lifecycle.
+
 `/continue` restarts the agent loop for the existing conversation without adding a new user message.
 
 `/status` shows a compact session overview: model, endpoint, context usage, message/turn counts, file access, mode flags, and state summaries (thinking, todo, snapshot, checkpoints, continue file).
 
-`/audit [path|glob]` runs a staged security audit over committed Git-tracked code. It triages files by attack surface, deep-reviews escalated files, verifies each finding with an isolated proof-of-concept agent, and writes patches and reports to `audit-findings/`. Pass `--resume` to continue a previous run, `--regen` to regenerate reports and patches for a completed run, `--workers N` to control parallelism. REPL-only. See [Security Audit](audit.md) for the full walkthrough.
+`/audit [path|glob]` runs a staged security audit over committed Git-tracked code. It triages files by attack surface, deep-reviews escalated files, verifies each finding with an isolated proof-of-concept agent, and writes patches and reports to `audit-findings/`. Pass `--resume` to continue a previous run, `--regen` to regenerate reports and patches for a completed run, `--workers N` to control parallelism, and `--debug` to write a real-time JSONL debug log to `.swival/audit/debug.jsonl`. Works in interactive (REPL) mode and in one-shot mode when `--oneshot-commands` is set. See [Security Audit](audit.md) for the full walkthrough.
 
 `/learn` reviews the current session for mistakes and confusions, then persists notes to `.swival/memory/MEMORY.md` for future sessions to learn from. On subsequent runs, memory entries are parsed by heading and selectively injected into the prompt using BM25 retrieval keyed from the user's question, keeping memory token cost bounded.
 
@@ -140,7 +142,7 @@ When `--profile` is combined with explicit flags like `--provider` or `--model`,
 
 `--temperature` controls sampling temperature and defaults to the provider default when omitted.
 
-`--top-p` controls nucleus sampling and defaults to `1.0`.
+`--top-p` controls nucleus sampling and defaults to the provider default when omitted.
 
 `--seed` passes a random seed for providers that support reproducible sampling.
 

docs/pages/audit.html

@@ -96,7 +96,7 @@ <h4>Reference</h4>
             <h1 id="swival-security-scanner">Swival Security Scanner</h1>
 <p>The <code>/audit</code> command runs a multi-phase security audit over committed Git-tracked code.</p>
 <p>It triages files by attack surface, performs deep review on escalated files, verifies each finding with an isolated proof-of-concept agent, generates patches, and writes structured reports. Only provable bugs survive to the final output.</p>
-<pre><code class="language-text">/audit [path|glob ...] [--resume] [--regen] [--workers N]
+<pre><code class="language-text">/audit [path|glob ...] [--resume] [--regen] [--workers N] [--debug]
 </code></pre>
 <p>Works in both interactive (REPL) and one-shot mode (requires <code>--oneshot-commands</code>). Runs against <code>HEAD</code>, so dirty working-directory changes are ignored.</p>
 <h2 id="quick-start">Quick Start</h2>
@@ -188,6 +188,9 @@ <h2 id="options">Options</h2>
 <p><code>--workers N</code> sets the number of parallel workers for triage and verification (default: 4). Verification is always capped at 2 regardless of this value.</p>
 <pre><code class="language-text">swival&gt; /audit --workers 8
 </code></pre>
+<p><code>--debug</code> writes a real-time JSONL trace of every audit step to <code>.swival/audit/debug.jsonl</code>. Useful when investigating a stuck phase, a missing finding, or unexpected resume behavior.</p>
+<pre><code class="language-text">swival&gt; /audit --debug
+</code></pre>
 <p>All options can be combined with a focus path:</p>
 <pre><code class="language-text">swival&gt; /audit src/api/ --resume --workers 6
 swival&gt; /audit src/api/ --regen

docs/pages/python-api.html

@@ -167,7 +167,6 @@ <h3 id="constructor">Constructor</h3>
     lifecycle_fail_closed: bool = False,
     lifecycle_enabled: bool = True,
     command_middleware: str | None = None,
-    aws_profile: str | None = None,
     approved_buckets: set[str] | None = None,
 )
 </code></pre>

docs/pages/tools.html

@@ -163,7 +163,7 @@ <h2 id="snapshot"><code>snapshot</code></h2>
 <h3 id="implicit-checkpoints">Implicit Checkpoints</h3>
 <p>Calling <code>save</code> before <code>restore</code> is not required. The system automatically creates implicit checkpoints at every user message, after each successful restore, and on conversation reset. When <code>restore</code> is called without a prior <code>save</code>, it collapses everything since the last implicit checkpoint, which is typically the most recent user message.</p>
 <h3 id="dirty-scopes">Dirty Scopes</h3>
-<p>Tools are classified as read-only or mutating. Read-only tools (<code>read_file</code>, <code>read_multiple_files</code>, <code>list_files</code>, <code>grep</code>, <code>fetch_url</code>, <code>view_image</code>, <code>think</code>, <code>todo</code>, <code>snapshot</code>) are safe to collapse because they don't change anything on disk. Mutating tools (<code>write_file</code>, <code>edit_file</code>, <code>delete_file</code>, <code>run_command</code>, unknown MCP tools, and A2A tools) dirty the scope.</p>
+<p>Tools are classified as read-only or mutating. Read-only tools (<code>read_file</code>, <code>read_multiple_files</code>, <code>list_files</code>, <code>grep</code>, <code>outline</code>, <code>fetch_url</code>, <code>view_image</code>, <code>think</code>, <code>todo</code>, <code>snapshot</code>) are safe to collapse because they don't change anything on disk. Mutating tools (<code>write_file</code>, <code>edit_file</code>, <code>delete_file</code>, <code>run_command</code>, unknown MCP tools, and A2A tools) dirty the scope.</p>
 <p>If the scope contains mutating tool calls, <code>restore</code> fails with a list of the dirty tools. Pass <code>force=true</code> to override when you are confident the summary captures the mutations.</p>
 <h3 id="snapshot-history">Snapshot History</h3>
 <p>Completed snapshots are preserved across context compaction. Up to 10 past summaries are retained and injected into the system prompt so knowledge survives aggressive compaction.</p>
@@ -199,6 +199,49 @@ <h2 id="mcp-tools">MCP Tools</h2>
 <h2 id="a2a-tools">A2A Tools</h2>
 <p>Swival can connect to remote agents via the <a href="https://google.github.io/A2A/">Agent-to-Agent (A2A) protocol</a>. A2A tools are discovered at startup and exposed alongside built-in tools. Unlike MCP tools, A2A tools always accept a natural-language <code>message</code> plus optional <code>context_id</code> and <code>task_id</code> for multi-turn conversations. A2A tool output is size-guarded the same way as MCP output, with continuation metadata preserved across size limits and context compaction. All A2A output is wrapped with an <code>[UNTRUSTED EXTERNAL CONTENT]</code> header, including spill files.</p>
 <p>See <a href="a2a.html">A2A</a> for configuration and details.</p>
+<h2 id="goal-tool-complete_goal">Goal Tool (<code>complete_goal</code>)</h2>
+<p>Goal state is started and controlled by the operator through <code>/goal</code>; the model cannot create, replace, pause, resume, or inspect goals through tools. Swival exposes exactly one goal tool during active goal work: <code>complete_goal</code>.</p>
+<p><code>complete_goal</code> takes no arguments and marks the active goal complete. Before calling it, the model is expected to run an evidence-based audit that maps every requirement in the objective to real files, command output, or tests. If the model is blocked or needs user input, it should return final text describing the blocker instead of calling <code>complete_goal</code>.</p>
+<p>After a turn that produces a final text answer with an active goal, the runtime injects a synthetic user message containing a continuation prompt. The continuation includes the objective verbatim as inert data, current usage, and remaining budget. Goal continuation turns count against <code>--max-turns</code> exactly like any other turn — the loop never bypasses the user's hard ceiling. If a continuation produces a final text answer with no tool calls, further continuations are suppressed to avoid a final-text loop, and the model's text is returned as a blocker/progress note.</p>
+<p>When the optional <code>token_budget</code> is reached, the goal transitions to <code>budget_limited</code>. The runtime injects a wrap-up steering prompt, and the dispatcher rejects mutating or work-starting tool calls (write/edit, command execution, subagents, MCP/A2A) with a fixed error string. Read-only tools (<code>read_file</code>, <code>grep</code>, <code>list_files</code>, <code>fetch_url</code>, <code>view_image</code>, <code>think</code>, <code>todo</code>, <code>snapshot</code>, <code>outline</code>) and <code>complete_goal</code> remain available for a coherent wrap-up.</p>
+<p>In one-shot mode (<code>swival "..."</code> with no <code>--repl</code>), <code>/goal &lt;objective&gt;</code> refuses because v1 has no slash syntax for <code>token_budget</code>. Use <code>--repl</code> for goal-driven continuation.</p>
+<p>Subagents do not receive the goal tools. Goals stay parent-session-only in v1.</p>
+<p>The session goal is wiped by <code>/clear</code>. Goals are not persisted across processes; crash recovery flows through <code>.swival/continue.md</code>, which records the active goal alongside todos, snapshots, and recent activity.</p>
+<p>The <code>/goal</code> slash command exposes the same state to the user:</p>
+<table>
+<thead>
+<tr>
+<th>Command</th>
+<th>Effect</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>/goal</code></td>
+<td>Show current goal status, or "No goal is currently set."</td>
+</tr>
+<tr>
+<td><code>/goal &lt;objective&gt;</code></td>
+<td>Create a goal (refused if one already exists).</td>
+</tr>
+<tr>
+<td><code>/goal replace &lt;objective&gt;</code></td>
+<td>Replace the existing goal and reset counters.</td>
+</tr>
+<tr>
+<td><code>/goal pause</code></td>
+<td>Pause the active goal.</td>
+</tr>
+<tr>
+<td><code>/goal resume</code></td>
+<td>Resume a paused goal.</td>
+</tr>
+<tr>
+<td><code>/goal clear</code></td>
+<td>Remove the current goal.</td>
+</tr>
+</tbody>
+</table>
         </article>
     </div>
     <footer class="site-footer">

docs/pages/usage.html

@@ -134,9 +134,10 @@ <h2 id="input-commands">Input Commands</h2>
 <p><code>/add-dir &lt;path&gt;</code> grants read and write access to an additional directory for the current session.</p>
 <p><code>/add-dir-ro &lt;path&gt;</code> grants read-only access to an additional directory. The agent can read, list, and grep files there but cannot write, edit, or delete them.</p>
 <p><code>/extend</code> doubles the current turn budget. <code>/extend &lt;N&gt;</code> sets the turn budget to an exact value.</p>
+<p><code>/goal</code> manages a persisted thread goal. With no argument, it prints the current goal status. <code>/goal &lt;objective&gt;</code> creates a goal and immediately starts the agent loop on it; the runtime then keeps issuing continuation prompts after each final answer until the model calls <code>complete_goal</code>, the goal is paused or cleared, or <code>--max-turns</code> is hit. <code>/goal replace &lt;objective&gt;</code> swaps in a new objective and resets the counters. <code>/goal pause</code>, <code>/goal resume</code>, and <code>/goal clear</code> adjust state without starting a turn. The set/replace forms are REPL-only — they refuse in one-shot mode because v1 has no slash syntax for the token budget required for unattended runs. See <a href="tools.html#goal-tool-complete_goal">Goal Tool</a> for the full lifecycle.</p>
 <p><code>/continue</code> restarts the agent loop for the existing conversation without adding a new user message.</p>
 <p><code>/status</code> shows a compact session overview: model, endpoint, context usage, message/turn counts, file access, mode flags, and state summaries (thinking, todo, snapshot, checkpoints, continue file).</p>
-<p><code>/audit [path|glob]</code> runs a staged security audit over committed Git-tracked code. It triages files by attack surface, deep-reviews escalated files, verifies each finding with an isolated proof-of-concept agent, and writes patches and reports to <code>audit-findings/</code>. Pass <code>--resume</code> to continue a previous run, <code>--regen</code> to regenerate reports and patches for a completed run, <code>--workers N</code> to control parallelism. REPL-only. See <a href="audit.html">Security Audit</a> for the full walkthrough.</p>
+<p><code>/audit [path|glob]</code> runs a staged security audit over committed Git-tracked code. It triages files by attack surface, deep-reviews escalated files, verifies each finding with an isolated proof-of-concept agent, and writes patches and reports to <code>audit-findings/</code>. Pass <code>--resume</code> to continue a previous run, <code>--regen</code> to regenerate reports and patches for a completed run, <code>--workers N</code> to control parallelism, and <code>--debug</code> to write a real-time JSONL debug log to <code>.swival/audit/debug.jsonl</code>. Works in interactive (REPL) mode and in one-shot mode when <code>--oneshot-commands</code> is set. See <a href="audit.html">Security Audit</a> for the full walkthrough.</p>
 <p><code>/learn</code> reviews the current session for mistakes and confusions, then persists notes to <code>.swival/memory/MEMORY.md</code> for future sessions to learn from. On subsequent runs, memory entries are parsed by heading and selectively injected into the prompt using BM25 retrieval keyed from the user's question, keeping memory token cost bounded.</p>
 <p><code>/simplify [focus]</code> inspects the codebase for low-risk simplification opportunities and applies them, preserving all observable behavior. Optionally scope it to a file or area (e.g. <code>/simplify swival/edit.py</code>). Prefers recently changed code but expands outward as needed.</p>
 <p><code>/tools</code> lists all tools available in the current session — built-in, MCP, and A2A — grouped by source with full descriptions.</p>
@@ -166,7 +167,7 @@ <h3 id="behavior-tuning-flags">Behavior Tuning Flags</h3>
 <p><code>--max-output-tokens</code> sets the model output budget per call and defaults to <code>32768</code>.</p>
 <p><code>--max-context-tokens</code> requests a context window size. With LM Studio, this may trigger a model reload.</p>
 <p><code>--temperature</code> controls sampling temperature and defaults to the provider default when omitted.</p>
-<p><code>--top-p</code> controls nucleus sampling and defaults to <code>1.0</code>.</p>
+<p><code>--top-p</code> controls nucleus sampling and defaults to the provider default when omitted.</p>
 <p><code>--seed</code> passes a random seed for providers that support reproducible sampling.</p>
 <p><code>--extra-body JSON</code> passes extra parameters to the LLM API call. The value must be a JSON object. This is useful for provider-specific or model-specific options that Swival does not expose as dedicated flags.</p>
 <pre><code class="language-sh">swival --extra-body '{&quot;chat_template_kwargs&quot;: {&quot;enable_thinking&quot;: false}}' &quot;task&quot;