@reticlehq/server 3.2.0 → 3.3.0

package/dist/telemetry/hud-metrics.js

@@ -0,0 +1,95 @@
+import { isHudControl } from '@reticlehq/core/hud';
+import { HudPanel, HudView } from '@reticlehq/core';
+/**
+ * How people use the in-page HUD, rolled into the session summary.
+ *
+ * Windowed like the tool histograms beside it: a periodic flush reports what happened since the
+ * last one, so a dashboard sums across a session's events. Names only — every key is a control id
+ * the wire schema already checked against core's closed list.
+ */
+/** How many steps of the journey one window keeps. A journey longer than this is cut, and says so. */
+export const HUD_JOURNEY_MAX = 60;
+export class HudMetrics {
+    #now;
+    #controls = new Map();
+    #viewMs = new Map();
+    #panelMs = new Map();
+    #journey = [];
+    #cut = false;
+    /** Did anything happen this window. A HUD merely sitting open is not worth a flush of its own. */
+    #changed = false;
+    #view;
+    #panel;
+    constructor(now) {
+        this.#now = now;
+    }
+    record(use) {
+        // A control the HUD never rendered is dropped here, the one place HUD use is counted, so free
+        // text cannot ride in on the id.
+        const control = use.control !== undefined && isHudControl(use.control) ? use.control : undefined;
+        if (control === undefined && use.view === undefined && use.panel === undefined)
+            return;
+        this.#changed = true;
+        if (control !== undefined) {
+            const key = use.toggle === undefined ? control : `${control}:${use.toggle}`;
+            this.#controls.set(key, (this.#controls.get(key) ?? 0) + 1);
+            this.#step(key);
+        }
+        if (use.view !== undefined && use.view !== this.#view?.value) {
+            this.#close(this.#view, this.#viewMs);
+            this.#view = { value: use.view, since: this.#now() };
+            this.#step(`view:${use.view}`);
+        }
+        if (use.panel !== undefined && use.panel !== this.#panel?.value) {
+            this.#close(this.#panel, this.#panelMs);
+            this.#panel = { value: use.panel, since: this.#now() };
+            if (use.panel !== HudPanel.NONE)
+                this.#step(`panel:${use.panel}`);
+        }
+    }
+    get empty() {
+        return !this.#changed;
+    }
+    /** The window so far. Open view and panel are counted up to now, and keep running after. */
+    summarize() {
+        const viewMs = this.#withOpen(this.#view, this.#viewMs);
+        const panelMs = this.#withOpen(this.#panel, this.#panelMs);
+        return {
+            ...(this.#controls.size > 0 ? { hudControls: Object.fromEntries(this.#controls) } : {}),
+            ...(viewMs.size > 0 ? { hudViewMs: Object.fromEntries(viewMs) } : {}),
+            ...(panelMs.size > 0 ? { hudPanelMs: Object.fromEntries(panelMs) } : {}),
+            ...(this.#journey.length > 0 ? { hudJourney: [...this.#journey] } : {}),
+            ...(this.#cut ? { hudJourneyCut: true } : {}),
+        };
+    }
+    /** Start the next window. The current view and panel carry over, timed from now. */
+    reset() {
+        const at = this.#now();
+        this.#controls.clear();
+        this.#viewMs.clear();
+        this.#panelMs.clear();
+        this.#journey.length = 0;
+        this.#cut = false;
+        this.#changed = false;
+        if (this.#view !== undefined)
+            this.#view = { ...this.#view, since: at };
+        if (this.#panel !== undefined)
+            this.#panel = { ...this.#panel, since: at };
+    }
+    #step(entry) {
+        if (this.#journey.length < HUD_JOURNEY_MAX)
+            this.#journey.push(entry);
+        else
+            this.#cut = true;
+    }
+    #close(open, into) {
+        if (open === undefined)
+            return;
+        into.set(open.value, (into.get(open.value) ?? 0) + Math.max(0, this.#now() - open.since));
+    }
+    #withOpen(open, closed) {
+        const out = new Map(closed);
+        this.#close(open, out);
+        return out;
+    }
+}

package/dist/telemetry/session-metrics.d.ts

@@ -16,6 +16,7 @@
  * than a rule saying it shouldn't.
  */
 import { BrowserLaunchKind, type ConnectFailure, type SessionSummary } from '@reticlehq/core/telemetry';
+import type { HudUseData } from '@reticlehq/core';
 /**
  * Mutable counters for one daemon lifetime. A plain class, not a store: it is process-local, it never
  * persists, and it dies with the daemon.
@@ -24,6 +25,8 @@ export declare class SessionMetrics {
     #private;
     /** Clock injected — this file must stay testable without a real one, per the repo's clock rule. */
     constructor(now: () => number);
+    /** A person used the HUD. Names only; the wire schema has already narrowed it. */
+    recordHudUse(use: HudUseData): void;
     /**
      * Record a call starting. Returns a function to call when it finishes — that closure is what makes
      * timing correct under CONCURRENCY: several agents can be inside `runTool` at once, so a single
@@ -162,5 +165,7 @@ export declare const recordSdkFailure: (failure: {
     site: string;
     message: string;
 }) => void;
+/** Narrow-and-record one HUD use. Keeps the session hot path to a single call. */
+export declare const recordHudUse: (use: HudUseData) => void;
 /** Tests only — drop the singleton so each case starts from zero. */
 export declare const resetSessionMetrics: () => void;

package/dist/telemetry/session-metrics.js

@@ -20,6 +20,7 @@ import { errorSkeleton, fingerprintError } from './error-fingerprint.js';
 import { describeToolParams } from './argument-shape.js';
 import { machineSnapshot } from './machine-snapshot.js';
 import { classifyError } from './error-class.js';
+import { HudMetrics } from './hud-metrics.js';
 /** Cap the distinct error shapes held in memory — a pathological loop must not grow unbounded. */
 const MAX_ERROR_KINDS = 40;
 /** Distinct tool names whose repeat-runs are tracked. Its own cap: the tool surface, not error shapes. */
@@ -165,10 +166,16 @@ export class SessionMetrics {
     #surface;
     #startedAt;
     #now;
+    #hud;
     /** Clock injected — this file must stay testable without a real one, per the repo's clock rule. */
     constructor(now) {
         this.#now = now;
         this.#startedAt = now();
+        this.#hud = new HudMetrics(now);
+    }
+    /** A person used the HUD. Names only; the wire schema has already narrowed it. */
+    recordHudUse(use) {
+        this.#hud.record(use);
     }
     /**
      * Record a call starting. Returns a function to call when it finishes — that closure is what makes
@@ -555,6 +562,7 @@ export class SessionMetrics {
             ...(this.#firstAppAt === undefined
                 ? {}
                 : { msToFirstApp: Math.max(0, this.#firstAppAt - this.#startedAt) }),
+            ...this.#hud.summarize(),
             final,
             // Only on a real exit. A periodic flush carrying `exit: "unknown"` would read as a daemon that
             // died without a shutdown path, which is the one thing this field exists to make visible.
@@ -613,7 +621,8 @@ export class SessionMetrics {
             0 === this.#bugsFound &&
             0 === this.#sdkFailures &&
             0 === this.#postSocketFailures &&
-            0 === this.#postRetriesSaved);
+            0 === this.#postRetriesSaved &&
+            this.#hud.empty);
     }
     /** Zero the counters after a non-final flush so the next flush reports the NEXT window, not a total. */
     reset() {
@@ -641,6 +650,7 @@ export class SessionMetrics {
         this.#unknownToolCalls = 0;
         this.#bugsFound = 0;
         this.#bugKinds.clear();
+        this.#hud.reset();
         // #seenBugKinds is deliberately NOT cleared. It is not a window counter — it is the
         // session-lifetime memory behind `repeat` on bug_found, and zeroing it made the same defect,
         // found again after a flush, report as a newly distinct one. Sessions run to 11.5 hours in the
@@ -665,6 +675,10 @@ export const recordBrowserLatency = (ms) => {
 export const recordSdkFailure = (failure) => {
     getSessionMetrics().recordSdkFailure(failure.site, failure.message);
 };
+/** Narrow-and-record one HUD use. Keeps the session hot path to a single call. */
+export const recordHudUse = (use) => {
+    getSessionMetrics().recordHudUse(use);
+};
 /** Tests only — drop the singleton so each case starts from zero. */
 export const resetSessionMetrics = () => {
     current = undefined;

package/dist/wire-journal.d.ts

@@ -0,0 +1,31 @@
+import { Bridge } from './portal/bridge/bridge.js';
+import { FlowStore } from './language/flows/flows.js';
+import type { FileSystemPort } from './memory/project/fs/fs-port.js';
+import type { TapeStep } from './memory/journal/drive-flow.js';
+import type { OnboardingStep } from '@reticlehq/core/telemetry';
+import { type PruneWorkspaceOptions } from './memory/journal/on-disk/startup-maintenance.js';
+/**
+ * Wire journal capture, ambient seeding and the journal-tail flush onto a bridge.
+ *
+ * Both entry points need all three, and both used to hand-roll them. `startDaemon` only ever wired the
+ * first, so on the path every user actually takes (`reticle serve` / `reticle mcp`) the journal tail was
+ * dropped at session end and the learned ambient map was never persisted OR seeded — meaning ambient
+ * learning could not converge across sessions and the last events of every session were lost. The two
+ * call sites had already drifted once before, which is why this is one function rather than a
+ * copy-paste both are asked to keep in step.
+ */
+export declare function attachJournal(bridge: Bridge, deps: {
+    fs: FileSystemPort;
+    reticleRoot: string;
+    enabled: boolean;
+    takeAmbientTape?: () => {
+        steps: readonly TapeStep[];
+        startPath?: string;
+    } | undefined;
+    reportStep?: (step: OnboardingStep) => Promise<boolean>;
+    /** Tell cloud sync a run landed, so it cycles instead of waiting for its timer. */
+    onRunPersisted?: () => void;
+    flows?: FlowStore;
+    /** What this project is willing to keep — the `retain` block of its `.reticle.json`. */
+    retain?: PruneWorkspaceOptions;
+}): void;

package/dist/wire-journal.js

@@ -0,0 +1,100 @@
+/**
+ * Journal wiring for the composition root.
+ *
+ * A sibling of `index.ts` rather than a move into `memory/journal/`: this is COMPOSITION, not
+ * journalling. It reaches the bridge, the flow store, the telemetry funnel and the recording tape to
+ * join them together, and putting those reaches inside the journal domain would make that domain
+ * depend on four areas it has no business knowing. `index.ts` already holds every one of them, and
+ * the 1000-line backstop is what asked for the split.
+ */
+import { artifactRootResolver } from './memory/project/artifact-root-resolver.js';
+import { originOf } from './portal/session/session-manager.js';
+import { Bridge } from './portal/bridge/bridge.js';
+import { FlowStore } from './language/flows/flows.js';
+import { makeJournalAttach } from './memory/journal/attach-journal.js';
+import { makeSessionEnd, recordDriveRun } from './memory/journal/session-end.js';
+import { attachDriveRunFlush } from './memory/journal/drive-run-flush.js';
+import { AmbientStore } from './memory/journal/ambient-store.js';
+import { ensureWorkspaceGitignore } from './memory/journal/on-disk/workspace-gitignore.js';
+import { pruneWorkspace, } from './memory/journal/on-disk/startup-maintenance.js';
+import { dirname } from 'node:path';
+import { findProjectConfig } from './command/cli/ports/resolve/cli-port.js';
+import { readBackgroundTraffic } from './portal/session/facts/background-traffic.js';
+/**
+ * Wire journal capture, ambient seeding and the journal-tail flush onto a bridge.
+ *
+ * Both entry points need all three, and both used to hand-roll them. `startDaemon` only ever wired the
+ * first, so on the path every user actually takes (`reticle serve` / `reticle mcp`) the journal tail was
+ * dropped at session end and the learned ambient map was never persisted OR seeded — meaning ambient
+ * learning could not converge across sessions and the last events of every session were lost. The two
+ * call sites had already drifted once before, which is why this is one function rather than a
+ * copy-paste both are asked to keep in step.
+ */
+export function attachJournal(bridge, deps) {
+    const journalAttach = makeJournalAttach(deps);
+    const ambientStore = new AmbientStore(deps.fs, deps.reticleRoot);
+    // Built once, not per session: the resolver walks config discovery and the user-level registry,
+    // and neither changes between two tabs connecting a second apart.
+    const resolveArtifactRoot = artifactRootResolver(deps.reticleRoot);
+    bridge.attachSessionCreate((session) => {
+        // Stamp the project's own `.reticle` before ANY counter fires for this session. Without it every
+        // verdict is recorded against wherever the daemon was started, which is how one app's evidence
+        // reached a different account's production dashboard.
+        // The origin is passed for the case where the page never stamped a project id: it is the only
+        // distinguishing fact left, and without it every such app shares one bucket.
+        session.artifactRoot = resolveArtifactRoot(session.projectId, originOf(session.url)).root;
+        // The project's config sits beside its `.reticle/`, so the declaration is read from the tab's
+        // own project rather than from wherever the daemon was started.
+        session.background = readBackgroundTraffic(findProjectConfig(dirname(session.artifactRoot)));
+        // Here rather than on the start path, which was neither the moment we were about to write into a
+        // repository nor the root we were about to write into: it created `.reticle/` — holding nothing
+        // but the ignore file — wherever the daemon was launched, coming back every boot after the user
+        // deleted it, while the journals this ignore protects landed in another tree, uncovered.
+        if (deps.enabled)
+            void ensureWorkspaceGitignore(deps.fs, session.artifactRoot);
+        journalAttach(session);
+        // Seed the learned ambient map so a fresh session starts knowing which regions churn, instead of
+        // re-learning from zero. Best-effort + async: a late seed still helps, a failure is silent.
+        if (deps.enabled) {
+            void ambientStore
+                .load()
+                .then((counts) => session.seedAmbient(counts))
+                .catch(() => undefined);
+        }
+    });
+    // Teardown: flush the journal tail to disk + persist what this session learned.
+    bridge.attachSessionEnd(makeSessionEnd({
+        ...deps,
+        ...(deps.retain === undefined ? {} : { retain: deps.retain }),
+        // Retention runs from teardown, and it must not delete the journal of a session that is still
+        // being written. The registry is the only thing that knows which those are.
+        liveSessionIds: () => new Set(bridge.sessions.all().map((s) => s.id)),
+    }));
+    /*
+     * And the same write, DURING the session rather than only at the end of it.
+     *
+     * Teardown was the only writer of a run artifact, so every verdict produced while a tab stayed
+     * open was invisible to cloud sync — which can only push artifacts that exist. Reported as "sync
+     * is not happening" and diagnosed as the agent forgetting to sync; there is no sync command to
+     * forget. The evidence simply was not on disk yet.
+     *
+     * Safe to call repeatedly because the run id is derived from the session, so this rewrites one
+     * artifact rather than accumulating them — a property `recordDriveRun` already had, for the
+     * unrelated reason that a reconnecting tab must not publish two overlapping rows.
+     */
+    if (deps.enabled) {
+        attachDriveRunFlush({
+            resolve: (sessionId) => bridge.sessions.get(sessionId),
+            write: (session) => recordDriveRun(deps, session),
+        });
+    }
+    // One call, because "what maintenance runs at startup" needs one answer. Inlined here, the byte
+    // budget was simply missing — written, tested, and called by nothing, while the three count
+    // bounds beside it ran every time. See startup-maintenance.ts.
+    //
+    // Deliberately NOT behind `deps.enabled`. Switching journalling off is what somebody does BECAUSE
+    // the directory got too big, and both sweep sites were gated on it, so that setting was the one
+    // under which nothing ever deleted what was already there. Visual diffs, feedback copies and run
+    // artifacts do not need the journal to be written at all and kept accumulating regardless.
+    void pruneWorkspace(deps.fs, deps.reticleRoot, new Set(bridge.sessions.all().map((s) => s.id)), deps.retain ?? {});
+}

package/docs/README.md

@@ -72,6 +72,7 @@ Everything here is published to [docs.reticle.sh](https://docs.reticle.sh) by `d
 | [vs-playwright-mcp.mdx](vs-playwright-mcp.mdx) | outside-in vs inside-out, and when Playwright is right |
 | [vs-chrome-devtools-mcp.mdx](vs-chrome-devtools-mcp.mdx) | cheaper per look, catches less: the trade, measured |
 | [vs-screenshots.mdx](vs-screenshots.mdx) | why a better vision model does not fix a non-visual bug |
+| [what-is-recorded.md](what-is-recorded.md) | what Reticle keeps, what is redacted, and what it takes for any of it to leave your machine |
 | [telemetry.md](telemetry.md) | what is collected, and how to turn it off |
 | [local-registry.md](local-registry.md) | installing an unpublished build |
 | [license-activation.mdx](license-activation.mdx) | you have a key: where to set it, how to confirm it, what to do when it fails |

package/docs/cli/cloud.mdx

@@ -101,7 +101,9 @@ reticle: no .reticle/cloud.json here ... run `reticle link` first
 
 ### `reticle push`
 
-Sends local run artifacts from `.reticle` to the linked project, honoring the sync policy. With `sync.runs` off it does nothing and says so. Prints `{ pushed, failed, total, project }`.
+Sends local run artifacts from `.reticle` to the linked project, honoring the sync policy. With `sync.runs` off it does nothing and says so. Prints `{ ok, project, sent, pulled }`, where `sent` carries the accepted counts and, when the server refused anything, a `rejected` array naming each artifact's index and reason.
+
+**A rejection is a failed push.** If the server refuses any artifact, `ok` is `false` and the command exits `1`, even when other artifacts in the same bundle landed. A refused artifact never reaches the dashboard and is re-offered on every cycle, so partial loss is still loss. `ok: true` and exit `0` mean everything offered was accepted, which includes the common case of a repo that was already up to date. The accepted counts still report what did land, so a partial push is visible as one.
 
 ### `reticle runs`
 
@@ -133,12 +135,12 @@ reticle: cloud not attached here ... run `reticle link` (or set RETICLE_CLOUD_UR
 
 ## Exit codes
 
-| Code | Meaning                                                                             |
-| ---- | ----------------------------------------------------------------------------------- |
-| `0`  | Success                                                                             |
-| `1`  | The API call failed, or the repository is not attached where attachment is required |
-| `2`  | Usage error, or not signed in and no `RETICLE_API_KEY`                              |
-| `3`  | `regression` only: at least one flow broke                                          |
+| Code | Meaning |
+| --- | --- |
+| `0` | Success |
+| `1` | The API call failed, the repository is not attached where attachment is required, or `push` had an artifact refused |
+| `2` | Usage error, or not signed in and no `RETICLE_API_KEY` |
+| `3` | `regression` only: at least one flow broke |
 
 Output is pretty-printed JSON on stdout. Errors and next-step nudges go to stderr, so an agent parsing stdout is unaffected.
 

package/docs/cli/init.mdx

@@ -19,6 +19,7 @@ npx @reticlehq/server init [--dry-run] [--port N] [--no-mcp] [--no-install] [--a
 | `--no-mcp` | boolean | `false` (MCP is registered) | Skip the MCP registration **and** the agent rule files (`CLAUDE.md`, `AGENTS.md`, `.cursor`) and the `/reticle` command |
 | `--no-install` | boolean | `false` (deps are installed) | Do not run the install. The step becomes `[⚠]` and prints the `add -D` command for you to run by hand, rather than vanishing from the plan |
 | `--app <dir>` | string | unset | Pick which app to wire in a monorepo, without changing directory |
+| `--hooks` | boolean | `false` | Also add a print-only Stop hook to `.claude/settings.json`, merged into what is there. When the agent stops without a claim that held, it prints one line; it never blocks. See [`reticle report`](/cli/report) |
 | `--yes` | boolean | `false` | Accepted for scripting. `init` has no interactive prompts today, so it is a no-op |
 
 <Warning>

package/docs/cli/report.mdx

@@ -0,0 +1,44 @@
+---
+title: reticle report
+description: What the latest session claimed, and what held. Also a print-only Stop hook for Claude Code.
+icon: clipboard-check
+---
+
+`reticle report` reads this project's most recent session from `.reticle/` and says how many of its claims held, how many failed, how many came back `unknown` and who can act on each, and how many proved nothing. It reads the journal on disk, so no daemon has to be running.
+
+```bash
+npx @reticlehq/server report [--session <id>] [--hook]
+```
+
+## Arguments and flags
+
+| Flag | Default | What it does |
+| --- | --- | --- |
+| `--session <id>` | the newest session | Report a specific session |
+| `--hook` | off | Print one line, and only when the working tree changed and no claim held |
+
+## What it prints
+
+```text
+session lease-85f8191b-3874-457b-973b-8ee365e5acfb
+2 of 4 claims held
+1 failed, 1 of them a green a channel contradicted
+1 unknown (environment: 1)
+  ✗ signal order:placed
+```
+
+An `unknown` is never counted as held. It is Reticle saying it could not tell, and the owner beside it says what to do next.
+
+## As a Claude Code Stop hook
+
+With `--hook` it prints nothing when a claim held or nothing in the tree changed, and otherwise one line, such as `Reticle: not verified. 3 claims: 1 failed, 2 unknown`. It prints Claude Code's `systemMessage` shape and always exits `0`: you see the line when the agent stops, and the agent is never blocked by it. `reticle init --hooks` adds it for you, merged into whatever `.claude/settings.json` already holds. By hand:
+
+```json
+{
+  "hooks": {
+    "Stop": [{ "hooks": [{ "type": "command", "command": "npx @reticlehq/server report --hook" }] }]
+  }
+}
+```
+
+A session last written more than an hour ago does not count as this turn, so a morning drive cannot answer for an afternoon edit. If you want the stop blocked until the change is verified, use [`reticle gate --hook`](/cli/gate) instead.

package/docs/desktop.mdx

@@ -214,7 +214,7 @@ Alternatively, since an Electron renderer _is_ Chromium, `--remote-debugging-por
 
 ```toml
 [dependencies]
-reticle-tauri = "3.2"
+reticle-tauri = "3.3"
 ```
 
 ```rust

package/docs/flows.md

@@ -87,6 +87,16 @@ reticle_flow {action:"load"}({ flowName: "create-task" })   // → the flow JSON
 reticle_flow_replay({ flowName: "create-task" }) // re-resolve each anchor against the LIVE DOM, run it
 ```
 
+## Delete a flow
+
+```jsonc
+reticle_flow {action:"delete"}({ flowName: "create-task" })  // → { deleted: true }
+```
+
+A renamed or obsolete flow otherwise lingers in `reticle_flow {action:"list"}` and in every `reticle_verify {action:"flows"}` suite run, where it fails forever against a screen nobody intends to keep.
+
+**Deleting a flow that is not there is an error, not a no-op.** It answers `{ error, code: "not_found" }` rather than `{ deleted: true }`, so a mistyped name cannot read as a completed cleanup while the real flow stays in the suite. Check the spelling against `reticle_flow {action:"list"}` and try again.
+
 **Watch it replay on the page.** When the presenter is on (`present: true`), a replay isn't silent. Each step drives the real page, so the synthetic cursor flies to the element, the focus ring lands, and the activity log streams the journey live. You (or a teammate) literally watch the saved journey re-walk itself on your app, then see the verdict land. It's the fastest way to _see_ that a flow still works, not just read a green checkmark.
 
 `reticle_flow_replay` returns a status:
@@ -164,6 +174,7 @@ With `apply: false` the flow file is **never modified**; you get the proposed di
 | `reticle_flow_save_recorded` | `{ flowName? }` | persist a human-recorded (toolbar) flow |
 | `reticle_flow {action:"list"}` | `{}` | flows on disk |
 | `reticle_flow {action:"load"}` | `{ flowName }` | the flow JSON |
+| `reticle_flow {action:"delete"}` | `{ flowName }` | `{ deleted: true }`, or `{ error, code }` (`not_found` when no such flow) |
 | `reticle_flow_replay` | `{ flowName }` | `{ status, steps, decision? }` (decision on drift/fail) |
 | `reticle_verify {action:"flows"}` | `{ names?, sessionId? }` | suite verdict `{ status, passed, failed, failures[] }` |
 | `reticle_verify { action: "heal" }` | `{ flowName, apply? }` | propose / apply nearest-match rebind |

package/docs/frameworks.mdx

@@ -35,6 +35,7 @@ Two columns say different things and it is worth keeping them apart. **CI gate**
 | **Plain HTML** | yes | no | no | no | Wired, unverified |
 | **Vue (non-Nuxt)** | as Vite | no | install only | no | Install gated, drive unverified |
 | **Preact** | as Vite | no | no | unproven | Sensor, React adapter via `preact/compat` |
+| **Server-rendered (Django, Flask, FastAPI, Streamlit, Rails)** | yes | no | no | no | Wired, unverified |
 
 <Warning>
   "Wired, unverified" means exactly that. The recipe exists and was written from a real integration,
@@ -85,7 +86,41 @@ module.exports = withReticle({/* your config */});
 
 ## Remix and Astro
 
-Both run on Vite, so both use the Vite plugin exactly as React does. Astro needs the React integration if you want component identity in `.jsx` islands. Static `.astro` markup gets DOM, network and routing without it.
+Remix uses the Vite plugin with `inject: false`: Remix SSRs its own HTML, so the plugin's connect-injection does not fire, but the stamping half still puts `file:line` on a verdict.
+
+Astro is the same on the plugin (wire it with `inject: false` if you want source pointers on JSX islands) and uses a different channel for the pairing token. `vite.define` does not reach Astro's client pipeline on 7.2+, so the identifier stays literal and the bridge refuses the dial. `init` reads the token in frontmatter and puts it on a `<meta name="reticle-pairing-token">`. Reading it per request also means a token written after the dev server started is picked up on the next load, with no restart.
+
+Use a processed page `<script>` with a static SDK import. Vite owns that module graph from the first transform:
+
+```astro
+---
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+const pairingToken = (() => {
+  if (!import.meta.env.DEV) return '';
+  const dir = process.env['RETICLE_PAIRING_TOKEN_DIR'] || join(homedir(), '.reticle');
+  try { return readFileSync(join(dir, 'pairing-token'), 'utf8').trim(); } catch { return ''; }
+})();
+const pairingRoot = import.meta.env.DEV ? process.cwd() : '';
+---
+<meta name="reticle-pairing-token" content={pairingToken} />
+<meta name="reticle-pairing-root" content={pairingRoot} />
+<script>
+  import { reticle, install } from '@reticlehq/react';
+  if (import.meta.env.DEV) {
+    const token = document.querySelector('meta[name="reticle-pairing-token"]')?.getAttribute('content') ?? '';
+    const root = document.querySelector('meta[name="reticle-pairing-root"]')?.getAttribute('content') ?? '';
+    install();
+    reticle.connect({
+      ...(0 < token.length ? { token } : {}),
+      ...(0 < root.length ? { root } : {}),
+    });
+  }
+</script>
+```
+
+The `<script>` tag must not sit inside a conditional. Astro hoists them statically, so `{isDev && (<script />)}` is never hoisted. `init` writes the same `<meta>` tags and a local `src/components/ReticleDev.ts` that the script statically imports. It also raises `vite.build.target` to `es2022` (Astro's default down-levels the SDK), declares the SDK in `optimizeDeps.include`, and keeps `.reticle/` out of the watcher. Static `.astro` markup still gets DOM, network and routing without the React integration.
 
 ## SvelteKit
 
@@ -205,6 +240,83 @@ The same shape works for webpack, Parcel, and the Vue and Svelte CLIs.
 
 Keep it out of your production template. Reticle self-disables when the build reports `NODE_ENV=production`, but a second lock on a door leading to your users is a reasonable number.
 
+## Server-rendered apps (Django, Flask, FastAPI, Rails)
+
+There is no JS build to import the SDK from, and no single template to paste a script tag into: an app has many templates and may not have a base one. The SDK loads from a URL instead, so a page with no build step is not a blocker.
+
+`reticle init` detects these and prints the right thing for the stack it found, writing `.reticle.json` as it goes. What follows is the same wiring, written down so you can read it before running anything, or wire it by hand.
+
+### Django
+
+Middleware is the Django-shaped answer: one place, runs for every page, no template to find.
+
+```python
+# reticle_dev.py: add to MIDDLEWARE while DEBUG is on:
+#   MIDDLEWARE = [..., "reticle_dev.ReticleDevMiddleware"]
+from django.conf import settings
+
+_SNIPPET = """<script type="module">
+  import { reticle } from 'https://cdn.jsdelivr.net/npm/@reticlehq/browser@<version>/+esm';
+  reticle.connect({ projectId: '<your-project-id>', token: '<pairing token>' });
+</script>"""
+
+
+class ReticleDevMiddleware:
+    """Inject the Reticle SDK into HTML responses during development only."""
+
+    def __init__(self, get_response):
+        self.get_response = get_response
+
+    def __call__(self, request):
+        response = self.get_response(request)
+        if not settings.DEBUG:
+            return response
+        if "text/html" not in response.get("Content-Type", ""):
+            return response
+        # Streaming responses have no .content to rewrite; leave them alone.
+        if getattr(response, "streaming", False):
+            return response
+        body = response.content.decode(response.charset)
+        if "</body>" not in body:
+            return response
+        response.content = body.replace("</body>", _SNIPPET + "</body>", 1).encode(
+            response.charset
+        )
+        if response.has_header("Content-Length"):
+            response["Content-Length"] = str(len(response.content))
+        return response
+```
+
+`reticle init` emits this with your real version, project id and pairing token filled in. Copy it from there rather than from this page: the placeholders above are the three things that have to be right.
+
+Four details in that middleware are load-bearing, and each is there because the obvious version is wrong:
+
+- **`settings.DEBUG`** is the guard. Reticle is dev-only, and this is the lock that cannot be forgotten at deploy time.
+- **the `text/html` check** keeps it from corrupting a JSON API response or a file download.
+- **the `streaming` check** exists because a `StreamingHttpResponse` has no `.content` to rewrite, and touching it raises.
+- **`</body>`, not `<head>`** so the SDK sees a parsed document.
+
+Re-setting `Content-Length` matters for the same reason: the body grew, and a stale length truncates the page in the browser rather than failing loudly.
+
+### Flask and FastAPI with Jinja
+
+Same shape, one hook instead of a middleware class: an `@app.after_request` in Flask, or a middleware in FastAPI, with the same four guards: a debug flag, `text/html` only, not streaming, and injected before `</body>`.
+
+### Streamlit
+
+Different again: Streamlit owns the top-level document, so there is no served template, and scripts passed to `st.markdown` do not run. Use `st.html` on Streamlit 1.63 or newer. `reticle init` prints the helper, which also guards against connecting twice across reruns.
+
+### What you get, and what you do not
+
+Everything that comes from reading the live page works: queries, snapshots, actions, network and console channels, verdicts.
+
+What is missing is the **source pointer**. `file:line` on a verdict comes from the build plugin stamping `data-reticle-source`, and there is no build step here to stamp it. You get every other signal and no `source` field, the same way a Vue single-file component does.
+
+<Warning>
+  Wired, unverified. No app in CI drives one of these to a verdict, so nothing will tell us if it
+  breaks. If a page does not register a session, that is worth reporting.
+</Warning>
+
 ## Desktop is a different shape
 
 Electron and Tauri invert the direction: your app dials the daemon, and there is no URL for an agent to open. Reticle also reaches the main-process and Rust IPC boundary, which the renderer cannot see.

package/docs/install-agentic.mdx

@@ -150,6 +150,42 @@ Four files in your project, none of them mysterious.
     ```
     The `projectId` is how Reticle scopes sessions to this project, so two apps running at once
     don't get confused for each other.
+
+    **Keeping `.reticle/` small.** Reticle bounds the directory for you, by count and by total size.
+    Add a `retain` block to change what it keeps:
+
+    ```json
+    {
+      "retain": { "sessions": 20, "visual": 10, "feedback": 20, "budgetMb": 512 }
+    }
+    ```
+
+    Those are the defaults, and every field is optional. `sessions` is how many session journals
+    survive, `visual` how many overlay diffs (pixel baselines are never deleted, because the next
+    comparison needs them), `feedback` how many local copies of reports already sent, and `budgetMb`
+    the total the whole evidence tier may occupy. `0` means keep none, and `"sessions": 0` also stops
+    journals being written in the first place.
+
+    Saved flows, capsules, baselines, the contract and the intent ledger are not touched by any of
+    this. They are the part meant to be committed, and a bound that deleted them would be deleting
+    the regression checks your team shares.
+
+    **Your app's own background calls.** An analytics or heartbeat endpoint on your app's own host
+    looks exactly like the app's work, so Reticle never guesses. If one of them keeps a verdict
+    waiting, or fails and gets blamed on an unrelated action, name it:
+
+    ```json
+    {
+      "background": ["/api/analytics/events", "/api/heartbeat"]
+    }
+    ```
+
+    Each entry is matched the way `urlContains` is. A listed request stops holding the wait open and
+    stops contradicting a claim; when a contradiction is still reported, it lists what was set aside.
+    It is never hidden from an assertion that names it: `net { urlContains: "/api/heartbeat" }` still
+    sees it. Keep entries specific: `/api` would set aside your whole backend.
+    Third-party calls (another site's beacon or SDK) need no entry; they are already set aside.
+
   </Accordion>
 
   <Accordion title="vite.config.ts (the plugin)">

package/docs/install-manual.mdx

@@ -175,7 +175,7 @@ Screenshots and headless mode need the Rust crate, which is versioned independen
 
 ```toml
 [dependencies]
-reticle-tauri = "3.2"
+reticle-tauri = "3.3"
 ```
 
 ```rust

package/docs/packages/tauri.mdx

@@ -21,7 +21,7 @@ Tauri IPC observation needs nothing on the Rust side. An `invoke('load_todos')`
 
 ```toml
 [dependencies]
-reticle-tauri = "3.2"
+reticle-tauri = "3.3"
 ```
 
 Its own dependencies are `tauri = "2"` plus the per-platform capture backends: `objc2` and friends on macOS, `webview2-com` and `windows` on Windows, `webkit2gtk` and `cairo-rs` on Linux and the BSDs.