# Configuration Pi Sych keeps credentials, provider choices, model identifiers, and personal examples outside the public package. Native Pi configuration owns provider authentication and MCP transport; Pi Sych configuration owns custom compaction policy, an optional completion reassessment, and the local literature path. ## Layered Pi Sych settings Pi Sych reads the global configuration from `/pi-sych/config.json` and independently reads an optional project override from `/.pi/pi-sych/config.json`. Global settings are applied first and project values override only keys they provide; `compaction` fields merge independently. Unknown keys are rejected. The version 2 shape is: ``` json { "version": 2, "compaction": { "custom": true, "thresholdTokens": 150000 }, "completionReassessment": false, "literatureDatabase": "library.sqlite" } ``` `compaction.custom` controls whether the Pi Sych workbench supplies its task-centred summary. When enabled, the proactive threshold defaults to 150,000 context tokens and triggers only at a safe settled/idle boundary. Pi may compact earlier when its own context-window safety rules require it; when the Pi Sych resource is loaded, it supplies the custom summary for those requests as well. `thresholdTokens` is not an alias for Pi's `reserveTokens`. Set custom to `false` to leave compaction to Pi's native behavior. `completionReassessment` defaults to `false`. When enabled, the workbench adds one hidden reassessment at Pi's final actionable `agent_before_settle` boundary after a completed run, only when there are no pending messages and Pi can continue. If the reassessment finds authorized work, Pi makes one continuation; if complete or genuinely blocked, it stops. A guard prevents repeated reassessments for that user message. This is separate from the 150,000-token compaction trigger and does not expand the existing request's authorization. `literatureDatabase` may be an absolute path or relative path. A relative global value is resolved from the global Pi Sych config directory; a relative project value is resolved from the project root and overrides the global library only for that project. If neither configuration supplies a value, Pi Sych uses `/literature.sqlite`. An existing project-local `LITERATURE.sqlite` takes precedence. The database is always opened read-only. See [v7 to v8 migration](migration-v7-to-v8.md) for obsolete v7 keys and native Pi replacements. ## Worker model catalogue and setup Workers use the conventional private catalogue `/worker-models.json`. Its role names, model identifiers, optional cost, and notes are user-maintained. For example: ``` json { "default": "mid coder", "models": { "mid coder": { "model": "provider/model", "cost": "low", "notes": "Routine edits and tests." } } } ``` `dispatch_worker` looks up the exact requested `modelRole`, or the catalogue's `default` role. Cost and notes are context for the supervisor; the runtime does not rank models or invent fallbacks. The tool also accepts optional inline `workerInstructions` for guidance specific to one launch. Pi Sych copies the configured worker agent directory to private temporary state and writes the supplied text to a launch-scoped `AGENTS.override.md`, preserving existing worker instructions before it. Pi loads this through native AGENTS discovery; project and ancestor AGENTS files retain Pi's normal precedence. The shared worker directory and project files are not modified. Omit the option to use the configured worker directory unchanged with no injected guidance. The model catalogue is needed to dispatch a worker, not merely to start Pi Sych for direct project work. A `project_status` check also reports the current supervisor model by exact `provider/model` match against this catalogue, without monitoring model changes. For a match it reports the role plus any defined `cost` and `notes` fields, without repeating the model ID. For no match or no catalogue it reports `role=none; not in catalog`. If Pi exposes no active model it reports `role=none; model unavailable`. Neither case is an error. Initialize the conventional `/worker-agent` directory once with the packaged bootstrap script. If a dispatch finds it uninitialized, `dispatch_worker` reports the bootstrap command. Ordinary workers have only their explicit tools. Remote retrieval is an explicit per-dispatch request and uses native Pi MCP/codemode configuration in that worker agent directory; Pi Sych does not copy or merge the supervisor's configuration. ## Worker context choice `dispatch_worker.contextMode` defaults to `clean`. Use `clean` when the explicit assignment, files, and selected skills provide enough context. Use `trajectory` when prior supervisor conversation materially improves the bounded assignment. Context need does not determine who must execute the task. The supervisor can explore or plan first, write relevant state into a plan, TODO, brief, or context file, and then delegate a clean task. Conversely, a simple direct request may be faster and clearer to complete in the supervisor without delegation. Trajectory mode requires a persisted exact tool-call boundary, creates a private native branch immediately before the assistant entry containing that dispatch, and fails clearly rather than falling back to clean. Context mode does not alter worker tools, permissions, model, skills, files, or research access. ## Local literature search `literature_search` is available directly to the supervisor. A dispatched worker also receives it when its selected skills include the exact `research` selector. Capability inspection checks whether the resolved database is absent, compatible with required v7 columns, or degraded; it does not verify access to underlying sources. Incompatible schemas report missing columns and the rebuild/migration requirement. See the [v7 literature database migration guide](literature-database-v7.md). The supported v7 schema stores canonical metadata in `papers` and uses an external-content FTS5 table named `papers_fts`: ``` sql CREATE TABLE papers ( id INTEGER PRIMARY KEY, filepath TEXT, directory TEXT, filename TEXT, year INTEGER, item_type TEXT, creators_json TEXT, title TEXT, abstract TEXT, topic_tags TEXT, doi TEXT ); CREATE VIRTUAL TABLE papers_fts USING fts5( filepath, title, abstract, topic_tags, doi, content='papers', content_rowid='id' ); ``` Maintain the external-content index outside Pi Sych; rebuild it after population with `INSERT INTO papers_fts(papers_fts) VALUES ('rebuild');`. Relative source paths resolve against the database directory. Creator-shape and SQL-null rules are specified in the public contract; malformed returned rows fail the query rather than returning partial results. Pi Sych performs shallow structural validation but does not infer creators, validate CSL semantics, format citations, or migrate older schemas. Search syntax is native FTS5. Useful query forms include quoted phrases, `AND`/`OR`, and column filters such as `title:`, `doi:`, and `topic_tags:`. Search results are discovery metadata and source-path handoffs, not source verification or evidence of collection completeness. Inspect the underlying source when exact wording, method, result, quotation, correction status, or precise metadata matters. A local source path can be inspected with an available PDF/document tool without loading an entire document into model context. ## Project canonical paths `SYNC.json` version 2 records tracked artifacts, fingerprints, and explicit dependency edges. It may relocate the project root and override canonical paths for `project`, `agents`, `style`, `evidence`, `decisions`, `todo`, and `inbox`. Artifact paths remain project-local. Worker context files may use a project-relative path or an explicitly selected readable absolute path. Worker-reported files and observed project changes are reported as project-relative paths. Configured canonical paths are trusted project configuration and may be external; path handling is not a sandbox boundary. ## Skill customization Pi Sych exposes seven umbrella skills: `project`, `write`, `analyze`, `code`, `review`, `research`, and `automation`. Their task recipes use relative links to local modules and shared methods. To customize one durably, copy its umbrella directory, its routed shared methods, and every routed module under other umbrellas, preserving their relative paths, into one of: ``` text /skills/ .pi/skills/ .agents/skills/ ``` Preserve the relative layout so recipe links continue to resolve. Named workers search `.pi/skills/`, then `.agents/skills/`, then the global Pi root's `skills/`, then packaged skills. Edit local `modules/*/examples.md` or shared `_methods/*/examples.md` first. Change guidance or task-recipe order only when you intentionally want different behavior. A project `STYLE.md` should record durable local deltas rather than copy package prose doctrine. Writing workers load `skills/write/DEFAULT_STYLE.md` as a package baseline and `STYLE.md`, when present, as a project override; explicit user, venue, renderer, accessibility, and evidence requirements remain higher precedence. These style resources are loaded only for workers selected with the `write` skill. ## Native Pi resource and MCP controls Use native Pi configuration and `pi config` to select independently loadable extensions and other Pi resources. Plannotator remains a separately selectable human-review adapter. Native Pi owns MCP transport and authentication: configure MCP in the worker agent directory, setting `PI_CODING_AGENT_DIR=/worker-agent` when running `pi mcp add`, `pi mcp list`, `pi mcp login`, or `pi mcp logout`. Use `/mcp` in a worker session to inspect its servers. Pi Sych does not maintain an MCP client or status/configuration wrapper. Remote research is explicit per worker dispatch; ordinary workers do not receive MCP or codemode. See the [migration guide](migration-v7-to-v8.md). An optional user-maintained `STACK.md` at `~/.pi/agent/STACK.md` may record durable computer/environment facts for computer-use work. It is machine context, not project software-stack state or capability availability; runtime state still determines what can be used now.