# Output Router Setup
Use this only when repository setup or repair explicitly includes Output Router, observed routing, generated-path hints, native safety-net routing, vault, thresholds, script-transform adapters, or script-transform repository config.
## Defaults
- Minimal `/setup-freeflow` writes only repository `defaultMode`. `.freeflow/config.json` remains required for activation; a local override cannot activate Freeflow.
- Output Router is repository-owned and disabled by default.
- Missing optional sections mean built-in defaults, not setup failure.
- Normal setup does not ask a generic capability question. If Output Router was not explicitly requested, do not write `outputRouter` config or install script adapters.
- If the user explicitly opts into Output Router during setup, write `outputRouter.enabled: true` directly. Do not make them run another command afterward.
- Observed routing is opt-in per producer/server. The user must choose persistence for each enabled entry before setup writes config.
- Preserve unrelated valid repository and personal settings. Do not copy Output Router config into `.freeflow/local.json`; only documented local-only processing settings belong there.
- Do not create a separate `setup-output-router` skill.
If the user says only “set up the output router” with no requested knobs, explain that enabling Output Router is enough for the router tools/guidance, then ask which optional subfeatures, if any, they want persisted. Recommend no subfeature config unless they need observed routing, repo-specific hints, script transform setup, or native safety-net behavior.
## Config Shape
Write only keys the user explicitly requests. Do not dump defaults and do not create empty optional objects. Output-router-related config lives under `outputRouter`. Do not write removed `capture` or `providers` config.
Supported shape:
```json
{
"defaultMode": "workflow",
"outputRouter": {
"enabled": true,
"postToolRouting": "safety-net",
"thresholds": {
"largeOutputBytes": 64000,
"largeOutputLines": 2000
},
"vault": {
"root": "~/.cache/freeflow-router/vault",
"retention": { "strategy": "ttl", "ttlDays": 7 }
},
"hints": {
"generatedPathGlobs": ["graphify-out/**"],
"noisyCommandPatterns": ["npm test"]
},
"observedRouting": {
"enabled": true,
"onRoutingFailure": "fail-open",
"mcp": {
"servers": {
"github": { "enabled": true, "persistence": "exact" },
"gmail": { "enabled": true, "persistence": "metadata-only" }
}
},
"web": { "enabled": true, "persistence": "exact" },
"fetch": { "enabled": true, "persistence": "exact" },
"codeSearch": { "enabled": true, "persistence": "exact" }
},
"scriptTransform": {
"enabled": true,
"sandbox": "auto",
"languages": ["javascript", "python", "jq"],
"network": "off",
"limits": {
"timeoutMs": 5000,
"maxInputBytes": 1048576,
"maxOutputBytes": 65536
},
"rawScriptPersistence": "disabled"
}
}
}
```
Rules:
- Top-level `enabled` and `skills.enabled` default to true after setup; write them only when the user explicitly wants to disable Freeflow or the skills layer.
- `outputRouter.enabled` defaults to `false`; write `true` only when the user chooses Output Router.
- `postToolRouting` defaults to `off`. Do not write `off`; use `safety-net` only when explicitly requested. Treat `strict` as reserved; ask before writing it.
- `thresholds.largeOutputBytes`, `thresholds.largeOutputLines`, and `vault.retention.ttlDays` must be positive integers.
- `vault.root` must be a non-empty string. Repo-local storage requires explicit user choice.
- `hints.generatedPathGlobs` are broad-scan generated-path hints. Explicit file or directory retrieval must remain available.
- `hints.noisyCommandPatterns` is parsed as hint config. Do not add it unless the user explicitly asks for command-pattern hints.
- `observedRouting.enabled` defaults to `false`; write it only when the user chooses observed routing.
- `observedRouting.onRoutingFailure` currently supports `fail-open`; omit it unless a caller needs an explicit non-default once supported.
- `observedRouting.mcp.servers` must contain explicit server entries only. Setup may discover configured servers for selection, but must not persist a volatile inventory of every installed tool.
- `observedRouting.web`, `observedRouting.fetch`, and `observedRouting.codeSearch` are Pi observed-routing producers. Enable only the producers the user chose.
- Every enabled observed-routing entry needs a user-chosen persistence mode: `exact`, `metadata-only`, or `none`.
- Recommend `exact` for public-ish evidence producers such as GitHub, web, fetch, and code search. Recommend `metadata-only` for sensitive or unknown producers such as Gmail, Slack, private customer systems, or likely-secret outputs.
- Do not offer or write `redacted`; it is reserved for future work and currently falls back to `metadata-only` with a warning if hand-edited.
- Pi public `freeflow_capture` and the separate `providers` setup surface have been removed. Do not write removed `capture` or `providers` config.
- `scriptTransform.enabled` defaults to `false`; write `true` only after an explicit script-execution opt-in.
- If the user opts into script transform setup and adapters are missing or unavailable, recommend installing global adapters. On consent, run `node <plugin-root>/router/dist/setup/script-transform-adapters.js install --config .freeflow/config.json`.
- The installer uses `~/.cache/freeflow-script-adapters` by default, or `FREEFLOW_SCRIPT_TRANSFORM_ADAPTERS_HOME` when set. It installs `quickjs-wasi@3.0.1`, `jq-wasm@1.2.0-jq-1.8.2`, `@bsull/eryx@0.5.0`, and `node@24` for the Python JSPI child runner, writes `freeflow-adapter-env.sh`, probes sandbox proofs, and updates `outputRouter.scriptTransform.languages` with only proof-passing languages.
- Freeflow auto-discovers adapters from that global cache. The explicit roots `FREEFLOW_QUICKJS_WASI_ROOT`, `FREEFLOW_JQ_WASM_ROOT`, and `FREEFLOW_ERYX_ROOT` remain overrides for custom installs.
- Python/Eryx is installed by setup and uses the setup-installed child Node process launched with `--experimental-wasm-jspi` when the host process lacks JSPI. It must not be marked available unless that child runner passes the required sandbox probes.
- `scriptTransform.languages` supports `javascript`, `python`, and `jq`; enable only languages whose adapters passed sandbox proofs.
- `scriptTransform.sandbox` currently supports `auto`, `network` supports only `off`, and `rawScriptPersistence` supports only `disabled`.
- `scriptTransform.limits.timeoutMs`, `maxInputBytes`, and `maxOutputBytes` must be positive integers within product caps. Per-call script limits may only tighten configured values.
## Verify
After writing optional capability config, use `freeflow_status` or equivalent direct inspection to verify:
- JSON parses.
- `defaultMode` is valid.
- A minimal shared setup with no optional settings contains only `defaultMode`.
- Newly added `enabled`, `interactionContract`, `skills.enabled`, `outputRouter`, `outputRouter.observedRouting`, and `outputRouter.scriptTransform` keys were requested; preserved valid settings remain unchanged.
- Invalid router, observed-routing, or script-transform values are not written.
- Output Router, observed routing, native safety-net routing, and script transform are not enabled unless explicitly requested.
- If script transform setup was accepted, global adapter install completed or a clear install/probe failure was reported, and enabled languages match proof-passing adapters.
- No observed-routing entry uses `redacted`, and every enabled entry has explicit persistence.
- `freeflow_status` shows effective defaults and migration recommendations without rewriting config.
- No repo-local hooks, skill files, setup-output-router skill, docs inventories, or repo-local storage directories were created.