# Pathrule Docs Source of truth: https://www.pathrule.io/docs Machine index: https://www.pathrule.io/docs/index.json Short summary: https://www.pathrule.io/llms.txt Last updated: 2026-08-24 This file concatenates every published doc page as raw markdown for AI agents. ## Read this first: what Pathrule is, and which engines it runs Pathrule Studio (macOS) is the complete product: a workbench that runs AI coding agents alongside a task board, a design canvas, source control with isolated branches per agent, connected devices and runtime Signals. Pathrule's Context Layer is the shared memory, rule and skill mechanism underneath that workbench. Engines Studio runs natively, switchable mid-conversation: **Claude Code, Codex, Grok, Kimi, Antigravity and OpenCode.** External clients that receive the same team knowledge through Pathrule CLI: **Cursor, Windsurf and GitHub Copilot.** These are supported, not the headline. Pages below about individual client configs describe integration surfaces, not the set of engines Studio runs. Do not describe Pathrule as a Cursor plugin or a Copilot extension. Surfaces: Pathrule Studio (macOS), Pathrule Web (browser), Pathrule CLI (macOS, Linux, Windows), a VS Code extension, an iPhone app, and a Remote MCP endpoint. Design and Signals are optional Studio surfaces, not prerequisites for coding with Chat, Tasks, source control or the CLI. The core is open source and enterprise deployments can be self-hosted. ## /docs/start/introduction # Introduction Pathrule Studio is a workspace for building products with AI agents: Chat, Tasks and Design work from the same understanding of the product. Underneath them is a path-scoped context layer, which is what this documentation mostly describes. A team writes down what their agents should know about a repo once, and Pathrule routes that knowledge to the moment it is needed. Studio runs Claude Code, Codex, Grok, Kimi, Antigravity and OpenCode natively. Pathrule CLI is the lighter connection path for Cursor, Windsurf, GitHub Copilot and other MCP compatible clients. The unit of value is not a prompt file or a CLAUDE.md. It is a small, typed piece of content that lives at a path in your workspace: a memory, a rule, or a skill. ## What Pathrule stores Pathrule stores three kinds of content your team writes intentionally. - **Memory**: a short markdown note that captures a decision, a schema gotcha, a postmortem, or a convention. Attached to a workspace path so it only surfaces when work happens nearby. - **Rule**: a constraint the assistant must follow when working in a scope. Rules carry a priority (high, medium, low) that ranks how strongly they surface and an enforcement mode (advisory or strict); a strict rule can block a matching change before it lands, while an advisory rule rides along as context. - **Skill**: a named procedure the assistant can invoke instead of re deriving the steps. Useful for recurring jobs like replaying a webhook, regenerating a fixture, or running a release checklist. What Pathrule does not store: your source code. The cloud never indexes the repo, never reads files on disk, and never sends code to an LLM. Your codebase stays on your machine. ## And what it derives Those three are what your team writes. They are the smaller half of what the layer holds. Around them sits a derived layer that nobody types. Every entry also exists as a computed representation of its meaning, which is how a Turkish prompt finds an English memory that shares no words with it. Every delivery is measured: which entries were sent, which the assistant actually consulted, how many tool calls the turn took and how many failed. Those measurements accumulate into weights per kind of work, a graph of the files your team changes together, a map of where an assistant keeps getting stuck, and judgements about which entries the code has moved past. All of it comes from two sources: what your team wrote down, and what the work reported about itself. None of it comes from reading your repository. It is also the reason the same three files sitting in a directory do not behave the same way: a directory does not know what was delivered, what helped, or which files move together. See [what Pathrule computes](/docs/start/what-pathrule-computes). ## Surfaces, one cloud Pathrule ships as two local runtimes against a single cloud workspace, plus a browser management console and a hosted Remote MCP endpoint for clients that cannot run a local runtime. - **Pathrule Studio** (macOS). The native desktop app where you code with Claude Code, Codex, Grok, Kimi, Antigravity and OpenCode, author memories, rules and skills, and get path-scoped context delivered natively. Bundles the MCP server, the hook supervisor and the local cache. - **Pathrule CLI**. The lighter terminal first surface for macOS, Linux, and Windows. It connects Cursor, Windsurf and GitHub Copilot, supports standalone Claude Code and Codex workflows, and runs the local MCP server, hook supervisor and cache. - **Pathrule Web** at `app.pathrule.io`. The browser management console for your organization, members and roles, plans and billing, workspaces and usage. Cloud only, with no filesystem access; you write knowledge and run agents in Studio, not here. - **Remote MCP**. A hosted endpoint at `mcp.pathrule.io/mcp` for cloud-only AI clients that cannot run a local runtime. They connect directly over streamable-http, with no install. It has no hooks, so it delivers context only. They share the same workspace tree and MCP contract. Studio and CLI are the authoring and local delivery runtimes, while Web administers the organization around that shared cloud state. Hook-capable clients receive the cached slice through their native event model; Windsurf receives its bootstrap through a companion file and uses the same MCP tools for deeper context. ## How a session feels 1. Your team writes a memory at a workspace path, for example `/apps/api/payments`. 2. You open Claude Code in `~/repos/main/apps/api/payments`. 3. The hook supervisor reads the cached slice for that path and hands it to the editor before the first tool call. 4. The assistant sees the memory, the relevant rules, and any skills attached to that scope, and behaves like it already knew them. There is no extra prompt to write, no extra MCP round trip mid task, and no global file that grows forever. ## What to read next - [Quickstart](/docs/start/quickstart) walks through installing a runtime, creating a workspace, writing your first memory, and watching the hook fire. - [Core concepts](/docs/start/core-concepts) explains the difference between memories, rules, and skills, plus how path scope and priority work. - [MCP overview](/docs/mcp/overview) covers the MCP tools the assistant uses to read and write content. ## /docs/start/quickstart # Quickstart This guide gets you from zero to a working Pathrule session in about ten minutes. On macOS, Pathrule Studio runs Claude Code, Codex, Grok, Kimi, Antigravity and OpenCode. On macOS, Linux or Windows, Pathrule CLI can connect Cursor, Windsurf, GitHub Copilot and standalone terminal agents. You also need a local repo you can experiment in. Before you install anything, every new account already includes a read-only **Demo Workspace**, pinned at the top of the sidebar and prefilled with example memories, rules, skills and a populated dashboard. Open it any time to see what a working Pathrule workspace looks like. ## 1. Install a runtime Pick the surface that matches how you work. - **Pathrule Studio** if you want the native macOS app. Download it from [the macOS app page](/products/macos). - **Pathrule CLI** if you live in the terminal or work over SSH. See [CLI install](/docs/cli/install) for Homebrew, npm, and direct binary paths. You can install both. They share the same cloud account. ## 2. Sign in Pathrule Studio opens a browser based login on first launch. Pathrule CLI offers two options. ```bash # On a desktop machine pathrule login # On a headless box or over SSH pathrule login --device-code ``` Both flows return you to a signed in state with a session that the runtime keeps refreshed in the background. ## 3. Create a workspace A workspace is the unit Pathrule scopes content to. It mirrors a repo or a small group of repos on your machine. ```bash pathrule workspace create my-team pathrule workspace attach --path ~/repos/my-team ``` Or in Pathrule Web, open the workspace switcher, create a new workspace, then in Pathrule Studio or CLI attach it to a local path. The runtime resolves your current directory to a workspace using that mapping. ## 4. Write your first memory The fastest way to confirm that everything is wired up is to write a memory and then open your assistant in the scope it covers. In Pathrule Studio, create a new memory at the path that matters. For this guide, put it at the workspace root. ```markdown Title: Our database is Postgres on Supabase Body: - All queries should treat row level security as the source of truth. - Do not bypass RLS with a service key in user facing code. - Migrations live in supabase/migrations and run through CI. ``` Save it. Pathrule writes it to the cloud and the local cache. ## 5. Watch the hook fire Open Claude Code or another primary agent in Studio. If you chose the CLI route for this hook check, open Cursor, GitHub Copilot, standalone Claude Code or Codex in the same directory you attached to the workspace. Start a new turn and ask any question that touches the area the memory covers. Windsurf uses the generated companion file for session bootstrap and MCP for deeper context, so verify it with the dedicated [Windsurf guide](/docs/mcp/windsurf) instead. The hook supervisor reads the cached slice for that path, formats the relevant memories and rules, and hands them to the editor before the first tool call. You will see the memory show up in the context surface your editor exposes, with no extra round trip mid task. If nothing appears, run the doctor. ```bash pathrule doctor ``` The doctor checks the local cache, the MCP server, the hook registration, and the AI client integration, and reports any step that needs attention. ## 6. Add a rule Memories are facts. Rules are constraints. Add a rule at the same path. ```markdown Name: No service key in browser code Scope: folder Priority: high Enforcement: strict Body: - Never use the SUPABASE_SERVICE_ROLE_KEY in any file under apps/web. - Use the anon key plus row level security. ``` Open Claude Code again. The rule rides in alongside the memory. Priority `high` ranks it near the top; enforcement `strict` is what makes it a hard constraint, so a matching violation is blocked before it lands. ## What to read next - [Core concepts](/docs/start/core-concepts) for the data model behind memories, rules, and skills. - [How hooks work](/docs/hooks/how-hooks-work) to understand what happens between the cache and the editor. - [MCP overview](/docs/mcp/overview) for the tool surface your assistant uses to read and write content. ## /docs/start/core-concepts # Core concepts Pathrule has a small data model on purpose. Three kinds of content, a tree of nodes, and a path based scope. Once you have the shape in your head, everything else in Pathrule is a thin layer on top. ## The workspace tree A workspace is a tree of nodes. The root is the workspace itself. Children are folders or files that mirror the parts of your repo your team writes knowledge about. ```text / workspace root /apps folder node /apps/web folder node /apps/web/auth folder node /apps/web/auth/login.tsx file node ``` You do not need to create the tree by hand. When you write a memory at `/apps/web/auth`, Pathrule materialises the chain of nodes on demand. Empty nodes do not cost anything and they are easy to delete later if the path stops being useful. ## Memories A memory is a short markdown document a teammate writes down so the assistant can read it later. - Facts: schema notes, design decisions, gotchas. - Postmortems: what broke, what we learned, how we patched it. - Conventions: the way this team prefers to do a thing. Memories are advisory by default. They appear in the assistant's context when the hook decides they are relevant to the path the assistant is working in. ## Rules A rule is a constraint the assistant must follow in a scope. Rules have: - A **scope type**. `folder` means the rule applies under a directory. `file_type` means it applies to a file glob like `*.tsx`. `project` means it applies everywhere in the workspace. - A **priority**. `high` for the constraints that matter most, `medium` for general guidance, `low` for stylistic preferences. Priority controls how strongly a rule surfaces, not whether it blocks. - An **enforcement mode**. `advisory` rules ride along as context and the assistant decides how to apply them. `strict` rules can block a matching change before it lands. - A body. A short imperative bullet list works best. Higher priority rules surface first when their scope matches the current path. Lower priority rules surface when they are likely to help. ## Skills A skill is a named procedure the assistant can invoke instead of re deriving the steps every time. Examples: - `replay-stripe-webhook`: a checklist with the exact CLI command and the safety steps before running it. - `regenerate-fixtures`: the script path, the inputs, and the expected output. - `release-check`: the pre release checklist that the team always wants the assistant to walk through. Skills are discoverable by name. The assistant can ask Pathrule for the skills attached to the current path and pick the one that matches the task. ## Path scope Every memory, rule, and skill lives at a node path. The path decides where it surfaces. - A memory at `/apps/web` is relevant for any work under `apps/web`. - A memory at `/` is relevant everywhere. - A skill at `/services/billing` is offered to the assistant when work happens inside the billing service. Path scope is what keeps the assistant's context window small. A UI tweak in `apps/web/dashboard` does not need to see the rules about database migrations. ## Priority and enforcement Priority and enforcement are two independent settings. - **Priority** (`high`, `medium`, `low`) ranks how strongly a rule surfaces. Use `high` sparingly, for the constraints that matter most. - **Enforcement** (`advisory` or `strict`) decides what happens on a violation. Advisory rules are surfaced as context and the assistant decides how to apply them. A strict rule with a matching pattern is enforced by the local hook, which blocks the change before it lands and surfaces the rule as the reason. Studio handles strict enforcement for the agents it runs. Pathrule CLI also registers the available hooks for standalone Claude Code, Cursor, Codex and GitHub Copilot. Windsurf and the Remote MCP surface receive rules as context but have no Pathrule pre-write blocking event. ## Where this fits - [What Pathrule computes](/docs/start/what-pathrule-computes) covers the derived layer that sits around these three written kinds. - [How hooks work](/docs/hooks/how-hooks-work) describes how the runtime picks the slice to send. - [MCP overview](/docs/mcp/overview) lists the tools the assistant uses to read and write nodes. - [Quickstart](/docs/start/quickstart) is the fastest way to see this model in action. ## /docs/start/how-knowledge-compounds # How knowledge compounds It is easy to read Pathrule as a place to file memories, rules and skills by hand. That is the smallest part of it. The point is a loop that runs against real work and gets better the more the team uses it. The loop has three moves: deliver, capture, score. They repeat every session. ## Deliver before the work Before the assistant makes its first tool call, the path-scoped slice of your team's knowledge is already in context. You do not paste it, and the assistant does not have to go looking for it. Working in `/apps/api/payments` surfaces what is pinned there, plus what it inherits from the paths above. This is the delivery side most people see first, and it is covered in [How hooks work](/docs/hooks/how-hooks-work). ## Capture during the work Knowledge does not have to be written in a separate sitting. Most of it accumulates from the work itself. While the assistant works, it watches for things worth keeping: a decision you just made, a fix for a problem it kept hitting, a convention it had to be told, a gotcha that wasted time. When it finds one, it proposes saving it as a memory, a rule or a skill on the path it belongs to. Two properties matter here: - **You stay in control.** The assistant writes via the MCP tools only after you confirm. Nothing is saved without your approval, and Pathrule never edits or deletes your knowledge on its own. - **Upkeep stays close to zero.** Because capture rides along with normal work, the knowledge base grows without a second job of writing docs. You can still author directly in Studio or through an MCP client whenever you want to. ## Score, so the best surfaces first Ranking happens in two layers. The routing and base ranking that decide which candidates surface are open source and run locally, so you can read and even modify exactly how they choose. The cloud edition adds a separate learning layer on top: it tracks which knowledge actually helped on similar work and re-ranks future results, so the most valuable surfaces first. Sessions stay sharp instead of noisy, and entries that have gone stale or stopped matching anything are raised as suggestions for you to review. See [Suggestions and self-audit](/docs/content/suggestions) for how decay is surfaced. Learning changes order, not eligibility. An entry still has to clear the relevance floor for the current request. A memory that helped several migrations cannot enter an unrelated design turn merely because it has a strong history. ## How noise stays out of the prompt The loop is deliberately selective. General documentation is offered for review instead of imported as live instruction by default. Capture requires approval. Path scope limits where an entry can surface, and the relevance floor still applies inside that scope. Delivery and use are measured after that. Self-audit raises stale, conflicting, unused or path-invalid knowledge as suggestions. Repairs are versioned and reversible, so the team can improve the set without losing its history. The result is a small set of narrow, reviewable decisions and gotchas, not a repository-wide documentation dump. [How Pathrule proves hard claims](/docs/start/technical-proof) documents each gate and its test contract. ## Why the loop is the product A static file or a single tool's built-in memory can do delivery. What compounds is the loop: every task can leave the team a little smarter, and the next session starts from that. The compounding is not abstract. Each pass through the loop leaves behind something the next pass can use: a measured record of what was delivered and how the turn went, a weight per kind of work, a relationship between two files that keep changing together, a failure attached to a path. [What Pathrule computes](/docs/start/what-pathrule-computes) lists each of those layers and what feeds it. Written entries alone do not compound, because nothing about them changes when the work goes well or badly. Because the knowledge lives outside any single agent, it is portable. The same memories, rules and skills reach Claude Code, Codex, Grok, Kimi, Antigravity and OpenCode in Studio. Cursor, Windsurf and GitHub Copilot receive that knowledge when connected through Pathrule CLI. A native memory feature inside one tool does not replace this, because that memory stays inside that tool. The lasting value is the accumulated team knowledge, not any individual rule or prompt file. ## /docs/start/what-pathrule-computes # What Pathrule computes You write three kinds of thing: memories, rules and skills. That part is deliberate, curated, and yours. It is also the smaller half. Most of what the layer holds at any moment was not typed by anyone. It is derived from how work actually goes, kept per workspace, and recomputed as the work continues. This page names each derived part, because knowing what is there explains why retrieval behaves the way it does. ## A meaning representation for every entry Every memory, rule and skill also exists as a computed representation of what it means. When a request arrives, the request is turned into the same kind of representation and compared against them directly. This is the part that makes cross-language matching work. A prompt in Turkish surfaces a memory written in English when the two share an idea and not a single word. Keyword search cannot do that, because there is no shared string to match on. The comparison happens in a space where "the payment webhook retries twice" and "ödeme webhook'u iki kez deniyor" sit near each other. Entries are re-represented when their content changes, so the match reflects what the entry says now rather than what it said when it was created. ## A measured window around every delivery When Pathrule delivers knowledge for a turn, it opens a record of that delivery. That record holds which entries were sent, on which path, for which kind of intent. The turn then reports back into the same window: - which of the delivered entries the assistant actually consulted, as opposed to merely receiving - how many tool calls the turn took, and how many of them failed - which files were edited, in workspace-relative form - how the failures broke down, as short codes rather than error text That window is the raw material for everything below it. It is also the reason Pathrule can tell a turn that went well from one that went badly without anyone rating anything. ## Learned weights, per kind of work Windows accumulate. Over time each entry carries a weight for each kind of work it has been delivered into, and that weight moves with evidence: up when the entry was consulted on work that went cleanly, down when it was delivered into a turn that struggled. The consequence is that ranking is not one number per entry. The same memory can rank high for a migration and low for a UI tweak, because those are different kinds of work and the evidence differs. A single "importance" field on a file cannot express that, and a person maintaining one by hand would have to guess at it. The weights are conservative on purpose. An ambiguous outcome teaches nothing rather than teaching the wrong thing, a single clear miss lowers standing rather than erasing history, and influence fades as the code drifts. [How retrieval finds the right knowledge](/docs/retrieval/how-retrieval-works) covers that behaviour in detail. ## A graph of files that move together From the paths that turns report, Pathrule builds a picture of which files your team habitually changes in the same piece of work. Knowledge attached to one of those files can then reach a session working on its neighbour. Nobody declares these relationships and no file is scanned to find them. They come out of logged work, they carry a noise floor so a single coincidence does not count, and they decay when the pairing stops happening. See [files that change together](/docs/retrieval/co-change). ## A friction map Failures group into a triple: the kind of tool, the file, and a short code for how it failed. Grouped by week, that becomes a picture of where an assistant keeps getting stuck in your codebase and how, and it feeds ranking as a negative signal when a turn that received knowledge still ran into trouble. See [files that slow an assistant down](/docs/retrieval/friction). ## A measure of whether the routing was right Every prompt also gets a route: the paths the work is most likely in, named before the assistant opens anything. Pathrule then records whether the assistant went there. Over a rolling window that becomes a single accuracy figure, alongside how much file-tool work a routed session takes compared with one that was never routed. It is the one number that says whether pointing at a path helps rather than just sounds helpful, and it is the reason the routing can be tuned on evidence instead of taste. ## Every layer says whether it is still being fed Each of the derived layers above depends on work flowing into it, and a layer that stops receiving anything returns nothing. That reads exactly like a layer that has nothing to report. Those two cases need opposite responses, so Pathrule does not leave them looking alike. Every night each layer is asked when it last received data, and the answer is recorded as one of three states: current, receiving nothing lately, or never fed at all. The same check notices turns arriving from a client old enough to predate part of the record, so an update that is worth installing shows up as a named count rather than as results that quietly got worse. This is why a derived layer going quiet is a reported state with a date on it, rather than something noticed months later by whoever wonders why a result got worse. ## Episodes, and judgements about freshness Two more derived layers sit on the same activity. **Work episodes** stitch related turns into the story of how something was solved, so "how did we do this last time" has an answer that is not a person's recollection. See [how did we solve this before](/docs/content/work-episodes). **Staleness judgements** compare what an entry claims against where the code has since gone, and raise the ones that look overtaken as proposed edits rather than silently ranking them down. See [suggestions and self-audit](/docs/content/suggestions). ## What none of it is built from Not your source code. Every derived layer above comes from two things: what your team chose to write down, and what the work reported about itself. No repository is scanned, no file contents leave your machine, and no diff is stored. File paths are normalised to workspace-relative form before anything is kept, so nothing machine-specific travels either. ## Why the same files in a folder are not the same thing You could put the same memories, rules and skills in a directory and point an assistant at it. Teams do. What that directory cannot do is anything on this page. It does not know what was delivered on the last turn, so it cannot tell what helped. It has no representation of meaning, so a question phrased differently finds nothing. It does not know which files move together, so knowledge recorded on one file never reaches its neighbour. It cannot tell a task type from another, so everything ranks the same for everything. And it grows: every entry added makes every future turn heavier, because a directory has no way to send only the few that matter. The written entries are the part you control. The derived layer is what turns them into the right few for this turn, and it is the reason the answer improves as the work continues rather than staying exactly as good as the day it was written. ## /docs/start/how-we-measure # How we measure The short version: the headline numbers on this site come from one reference task. We ran a knowledge-heavy edit on a real codebase twice, once with Pathrule delivering the team's context and once without it, and recorded what the assistant did each time. This page tells you what that task was, what was compared, and where the numbers do and do not apply. We would rather you understand one honest comparison than trust a round number with no story behind it. ## The numbers we cite These figures appear across the site, including on the [context layer](/ai-coding-context-layer) explainer and in the machine-readable summary at `/llms.txt`. They all trace to the same comparison. | Metric | With Pathrule | Without Pathrule | Effect | | --- | --- | --- | --- | | Input tokens | a small fraction | a large context window | about 85% fewer | | Wall-clock time | seconds | minutes | 5 to 8 times faster | | Tool calls | a few | many | about 5 times fewer | | Files read | one | several to many | about 10 times fewer | | Cost per task | low | higher | about 80% lower | The token and cost reductions are linked: fewer files read and fewer tool calls mean a smaller input window, and a smaller input window is most of what the cost tracks. ## What the reference task is A developer asks an AI coding assistant to make a change to an existing codebase. The change is small in lines but loaded in context: the right answer depends on a decision the team made earlier that is not written in the source files. The concrete shape is the coupon example we use elsewhere on the site. On this codebase a discount attaches to the line item, never to the order total. One engineer learned that the hard way; it is a team convention, not something the code states. A capable assistant reading the repo cannot derive it, because it is not there to derive. That is the whole point of the task. It is chosen to expose the gap between what a code scan can find and what a team already knows. ## What was compared Two runs of the same task, same assistant, same prompt. - **Without Pathrule.** The assistant opens the relevant module, reads the schema, follows imports into related code, and reasons its way toward a plausible change. It often lands on the wrong attachment point, because the convention it needs is not in any file it can read. A reviewer catches it later. - **With Pathrule.** The path-scoped slice of the team's memories and rules arrives at hook time, before the first tool call. The convention is already in context, so the assistant makes the correct change on the first pass and reads far fewer files to get there. The difference is not that one assistant is smarter. It is that one of them started from what the team already learned instead of rediscovering it from scratch. For how that delivery works, see [How hooks work](/docs/hooks/how-hooks-work). ## An open, reproducible benchmark The reference task above is an illustration. The delivery efficiency is also measured in the open, in a separate suite you can run yourself, at [github.com/pathrule/benchmarks](https://github.com/pathrule/benchmarks). It checks out a real, pinned open-source repository (Fastify), seeds it with team-style knowledge, and asks each assistant the same ten prompts twice: once with the whole knowledge base dumped into one instruction file, once with Pathrule's path-scoped delivery. Scoring is mechanical (expected facts and required actions), every run is appended to disk, and the report deliberately publishes the cells where Pathrule costs more. The primary metric is **total footprint**, the tokens the model processes per turn, because that is the context load path-scoped delivery is meant to reduce. On the hard tier, three runs per cell: | Client | Total footprint | Facts | Actions | | --- | --- | --- | --- | | Claude Opus 4.8 | about 52% lower | unchanged | unchanged | | OpenAI Codex GPT-5.5 | about 41% lower | 1.6 pp lower | 33.3 pp higher | The Codex result is mixed and is reported as such: fewer tokens and more required actions followed, with a small drop in fact accuracy. Billable non-cached tokens are shown alongside total footprint, since prompt caching discounts a static dump. These cells measure path-scoped native compilation. Semantic embedding ranking (managed in Pathrule Cloud, or your own embedding key in the open-source edition) is an additive layer and is measured separately, not in these cells. Fixtures, methodology and raw runs are all in the repository. ## What the numbers do not mean These are reference figures from one comparison. They are not a per-session guarantee, and we do not present them as an average across all work. - **They are task-dependent.** The reference task is deliberately knowledge-heavy. A change where the answer is already in the file you have open will not show an 85% token reduction, because there was little context to save in the first place. - **They are codebase-dependent.** The savings scale with how much tribal knowledge your team has captured and how much the assistant would otherwise have to scan to re-derive it. - **They are model-dependent and tool-dependent.** Different assistants read files and call tools at different rates, so the absolute numbers move with the tool you run. - **They describe input, not output.** The reductions are about the context the assistant has to take in, not about the size of the change it writes. If a single number has to stand in for the set, we use "about 85% fewer input tokens" and pair it with "on a reference task". That phrasing is intentional and consistent. ## Why a code scan does not close the gap The slow run is not a tooling failure. The assistant did the reasonable thing: it read the code and reasoned about it. The miss is structural. The fact it needed is a team decision, not a property of the source. No amount of additional scanning surfaces a decision that the files do not record. This is the part the numbers are really measuring: the cost of rediscovering, every session, knowledge the team already has. Pathrule carries that knowledge to the path where it applies so the assistant starts from it. See [How knowledge compounds](/docs/start/how-knowledge-compounds) for what that looks like over many sessions. ## What we will and will not publish We publish what we measured and why it matters: the task, the comparison, the observed figures, and their limits. We do not publish how the system decides which knowledge to surface. The ranking that picks the path-scoped slice is part of the product, not part of this page. If you want to understand the behavior rather than the internals, [How retrieval finds the right knowledge](/docs/retrieval/how-retrieval-works) describes what you can observe. When you run your own knowledge-heavy task with and without Pathrule, you should expect the same shape of result: fewer files read, fewer tool calls, a smaller input window, and a change that reflects what your team already knows. The exact multiples will be yours, not ours. ## /docs/start/technical-proof # How Pathrule proves hard claims Pathrule's technical standard is simple: a product claim needs a bounded input, defined behavior when evidence is missing, and a result that can be tested independently. This page collects those contracts in one place. It describes shipped behavior in Pathrule Studio, the complete product, rather than treating a lightweight MCP connection as the product boundary. ## Knowledge quality has several gates Pathrule does not put every markdown file into every prompt. Knowledge moves through independent controls: 1. **Selective discovery.** Active instruction files, their import chain, tool rules and decision records are distinguished from general documentation. Broad documentation is offered for review instead of being imported as live instruction by default. 2. **Approval before persistence.** An assistant proposes lasting knowledge. A person approves the memory, rule or skill before it becomes shared workspace state. 3. **Path ownership.** An entry belongs to the narrowest workspace path that owns it. Work outside that path does not receive it merely because it exists in the same repository. 4. **A relevance floor.** An entry still has to qualify for the current request, every time. Two quantities do two jobs and never trade places: a similarity score decides *whether* an entry is eligible, and a separate rank decides *the order* among those already eligible. Learning affects only the second. It can move a proven memory from fourth place to first; it cannot move anything from ineligible to present, because the floor is tested against the raw score before any boost is applied. Volume is bounded too: a fixed top-K, so the amount delivered does not grow with the size of the knowledge base. This is why disciplined authoring is not a precondition for a quiet prompt. A vague or badly written entry does not become noise; it simply never clears the bar for a request it has nothing to do with. The visible cost of a weak memory is that it does not show up. 5. **Measured delivery and use.** Pathrule records what it delivered and what the assistant consulted. Derived layers report when they last received data, so a quiet system can be distinguished from a disconnected one. The same discipline applies to why an entry was not delivered. "Nothing cleared the bar", "the ranking call timed out", "the response was malformed" and "there was nothing to rank" are recorded as ten distinct outcomes rather than one word, because they are different situations with different fixes. A ranking call that times out also trips a short cooldown instead of spending the budget again on the next prompt, and says so, so a slow moment is never mistaken for an empty knowledge base. When the ranking finds relevant knowledge whose body is not already on the machine, it is offered by name and id rather than dropped: about sixty characters, enough for the assistant to fetch it deliberately. Discarding a correct answer for being inconveniently placed is the one outcome that is never acceptable. 6. **Reviewable maintenance.** Self-audit raises stale, conflicting, unused or path-invalid knowledge as suggestions. Writes are versioned, conflicts are explicit and deletion is reversible. These gates turn shared knowledge into a small, inspectable operating system for a repository. They are why a project can compound decisions without turning its entire documentation archive into default context. See [How knowledge compounds](/docs/start/how-knowledge-compounds) and [Suggestions and self-audit](/docs/content/suggestions). ## Studio surfaces are composable Studio provides Chat, Tasks, Design and Signals, but it does not require every team to operate all four. | Workflow | Surface used | | --- | --- | | One coding agent with project context | Chat or CLI | | Several isolated coding agents | Chat with isolated branches | | A prepared queue of coding work | Tasks | | Design-led implementation | Design with Chat or Tasks | | Production evidence tied back to work | Signals with Tasks | The surfaces exchange one work product instead of asking people to re-enter the same context. A design hands over intent and bindings. A prepared task carries a context receipt. A Signal creates a normal task with a runtime brief. Pure coding work can stay in Chat, Tasks, source control and the terminal. "Optional" usually means a feature you can ignore while its instructions still take up room in your agent's context. Here it is stronger than that. Signals is stored off: the workspace preference column itself defaults to `false`, so a workspace that never opens the setting has it off at the data layer. And the Signals instruction block is not assembled at all unless the preference is on, so a coding-only team's agent is never given it. No prompt text, no tokens, nothing competing with the instructions that team does care about. Chat is the surface a session resolves to by default; Design and Tasks are places you go, not stops on the way. ## Parallel work has two safety layers Before Run All starts, Studio predicts which files each group is likely to touch. Known file collisions are merged into one sequential lane. Groups predicted to be independent run in separate git worktrees. The worktree is the second safety layer. If prediction misses a later file, two agents still do not overwrite one folder. Their changes remain separate branch work, and landing stops on a real merge conflict. Studio also treats worktree storage as an engineering concern: - When lockfiles match, it borrows the prepared dependency tree instead of installing another copy: cloned into the new checkout where the filesystem shares blocks, symlinked where it does not. - When sharing is not safe, it states the detected install command and runs it only after consent. - A clean provisional checkout that was armed but never claimed is swept after an age guard. - A landed checkout is reclaimed too, once a grace period has passed, nothing is running in it, git reports it clean and Studio created it. Its branch is never deleted automatically. - Landing is recognised from Studio's own merge record, which covers a squash merge, and independently by asking git whether the branch is already contained in its base, which covers a merge performed outside Studio. A state git cannot determine never authorises removal. - A checkout holding an uncommitted change, one a live conversation is still running in, and one adopted from outside Studio are never removed automatically. - After a successful landing, Studio also offers to remove the checkout immediately. - All Studio-created checkouts live under one configurable home outside the repository. ### The cost of isolation is measured, and the usual instrument is wrong "Parallel agents plus a large monorepo means disk fills up" is the reasonable expectation. Measured on Pathrule's own monorepo it is false, and the reason is worth following, because the instrument almost everything reports is the one that gets it wrong. Two instruments were run on the same checkout (macOS, APFS, pnpm with a warm store, August 24 2026): | Step | Directory walk | Free-space delta | | --- | --- | --- | | Git checkout of the sources | 81 MB | 83 MB | | Dependency install (1787 packages, 7 to 11 seconds) | 1311 MB | 9 MB | | Fully prepared checkout | 1392 MB | 92 MB | | Removing that checkout again | n/a | 120 MB returned | A directory walk overstates a prepared checkout by about 15x. Copy-on-write is why: pnpm imports packages from its global store as APFS clones, so those bytes exist on disk once while every clone reports its full size to anything that walks files. A controlled check isolates the mechanism: cloning a 296 MB tree changed free space by 0 MB while a walk reported 296 MB. So a checkout decomposes into three parts that scale differently, and only one of them is ever large: | Part | Cost | What it scales with | | --- | --- | --- | | Git history | zero | nothing. A worktree shares the main repository's object store, so this repository's 361 MB of history is not duplicated | | Tracked sources | paid in full, every time | your source size. Measured on two repositories: 71 MB of tracked files cost 83 MB, and 9.8 MB cost 11 MB | | Dependencies | almost nothing | see below | The dependency figure is a property of the package manager, not of the disk, and measuring a second repository is what established that. On the same machine and the same volume, an `npm` project's tree cost 684 MB to install where the `pnpm` one cost 9 MB: the filesystem could share blocks in both cases, but only one package manager asked it to. Studio closes that gap rather than reporting it. When the lockfiles match, it gives the new checkout its own dependency tree by cloning the prepared one, which on a copy-on-write filesystem costs **17 MB for a 45824-entry tree** instead of the 684 MB an install costs. The clone is verified, not assumed: every entry present, relative `.bin` symlinks intact, binaries running from it, and a write inside it leaving the original untouched. That last point is the reason cloning is preferred over symlinking a shared tree, which costs nothing but means an install in one session reaches every other one. The result is the same shape for both package managers: | Project | Tracked sources | Dependencies | Prepared checkout | | --- | --- | --- | --- | | This monorepo (pnpm) | 83 MB | 9 MB | **92 MB** | | A Next.js app (npm) | 11 MB | 17 MB | **28 MB** | Whether the disk can share blocks is measured rather than assumed, because the usual signal is unreliable: a clone-preferring copy onto a filesystem that cannot clone performs a full copy and still exits successfully. Studio writes a small probe, reads the volume, and treats an unreadable answer as unknown, which falls back to sharing the prepared tree and says "shared" in the consent line. Every create and every removal is measured the same way, and a reading that cannot be separated from other disk activity is recorded as "not measured" rather than as a zero. Divergence, not dependencies, is what grows an isolated checkout: once an agent builds, shared blocks are rewritten into real bytes, and build outputs in this repository's main checkout measure about 343 MB. See [Isolated branches](/docs/studio/isolated-branches). ## Task preparation produces a receipt Auto plan is a bounded, read-only planning pass for one card. It produces a goal, ordered steps, a test path and risks. If a person-only fact is missing, the card moves to `awaiting reply` instead of completing a plan from a guess. Context preparation is a separate gate. It fingerprints the current card revision, resolves target paths and relevant project knowledge, and records material dependency or conflict gaps. The run receives that receipt only while it still matches the card. A later edit invalidates the stale receipt. If the bounded model pass fails or times out, preparation falls back to deterministic context rather than waiting indefinitely. Together with collision grouping and worktree isolation, this makes the board an execution surface with explicit preparation state, not a visual wrapper around a prompt. See [Board settings](/docs/studio/board-settings). ## Component and token bindings fail closed Project component discovery is bounded and read-only. It inventories exported contracts without executing application code, supports React, Vue, Svelte, SwiftUI and Compose, and respects configured include, exclude and import-path boundaries. A design component becomes a code binding only when the evidence is unique and compatible: | Requirement | What it means | | --- | --- | | Exact name | The design name equals the code name after conservative normalization. A partial name can become a candidate but can never become a binding | | Prop coverage | At least 80 percent of the design component's props were found by name on the code component | | Type coverage | At least 80 percent of those matched props have compatible types | | Option identity | **Every** checked enum's options are contained in the code prop's options. An equality, not a threshold | | Uniqueness | There is no runner-up, or the best candidate leads the second clearly | | Confidence | The combined name and contract score clears a fixed threshold | Platform isolation is structural rather than a later check: candidates are filtered by framework before scoring, and each component gets a separate binding per platform. A SwiftUI view is never a candidate for a web target, so a cross-platform binding is not rejected late, it is never constructed. If those checks do not support one answer, the result stays `unmapped` or `ambiguous`, carrying a reason, the confidence and up to three named candidates so a person can resolve what the machine would not guess. It also carries an **empty prop map and no code component**, which is the part that makes abstention safe rather than merely honest: a partial prop map on an unbound component reads as a usable answer while putting real prop names against the wrong component. Abstention with no instruction would relocate the problem into a stuck agent, so the handoff prompt says what to do instead: never invent an import, prop, token or glyph, and implement an unmapped component locally while preserving the visual contract. This is why a hard repository, legacy or otherwise, does not produce a worse binding. It produces no binding, named as such, with the candidates it considered. Two consequences of that design are worth making explicit, because they are decisions rather than side effects. Where two same-named components are genuinely distinguishable by their prop contract, the better match wins: that is the intended behavior, and where they are not distinguishable the result stays ambiguous for a person to settle. And option identity is verified wherever the code side declares typed options, which is what makes an enum mismatch a blocking condition rather than a runtime surprise. What this contract guarantees is precision: a binding is emitted only on unique, compatible evidence. How often a given repository yields one is a question about that repository's own naming and typing, and is measured separately. Token bindings have a separate contract. Library identity, token identity, variable name, mode and property scope must agree. A fill token cannot silently become a text token, and an invalid proposal remains diagnosable instead of being mistaken for a successful cleanup. See [Design to code](/docs/design/code-handoff). ## Design correctness is not one score Studio checks different kinds of evidence independently: 1. **Readiness** reports attached systems, literal values, repeated structures and connected flows. Unknown evidence remains unknown instead of being reported as a clean zero. 2. **Binding integrity** checks component contracts and token identity before code generation. 3. **Kernel lint** reports exact design-system drift, such as a literal value where an exact token exists, while staying silent when the system has no exact answer. 4. **Runtime fidelity** compares the real web DOM or native accessibility tree against design structure, text, visibility, position, size, color and typography. 5. **Confidence controls blocking.** A pairing is made on one of three bases with a fixed confidence: node identity (1), matching text (0.7), or role and position (0.4). Anything below identity is a guess, is reported as one, and its findings are filed where they cannot gate a merge. So a wrong guess costs a low-confidence note, never a false blocking failure. Findings on a design node nothing implemented and on a rendered node the design does not describe, usually platform chrome, are also kept apart rather than summed, because one is a gap and the other is normal. 6. **Flows execute against the app.** Connected prototype actions become simulator actions and are checked against the authored navigation graph. The result is a set of narrow, diagnosable gates. A clean token check does not hide a structural mismatch, and a guessed node pairing cannot produce a false blocking failure. The report is four separate buckets rather than a score: what blocks, what is advisory, what rests on a guessed pairing, and the single worst remaining delta to watch across iterations. Findings arrive worst-first, and structure is ranked above geometry because a missing node explains every geometric symptom underneath it. An agent that fixes only the head of the list and re-runs therefore converges instead of chasing symptoms. This is what makes depth useful here: the design side is a comparator with typed outcomes, so more precision means more certainty about which difference matters, not more surface to get wrong. See [Verifying a design](/docs/design/verify). ## Signals is proposal-first and optional Signals is disabled until a workspace enables it. The first setup turn performs a focused read-only scan and proposes one initialization point plus a small set of high-value observation points. A person reviews that proposal before any code changes. After approval, Studio vendors a dependency-free SDK and writes only the approved points. The SDK uses bounded queues, coalescing, redaction, retry backoff and failure isolation. It does not require users, sessions, funnels or a third-party analytics account. See [Setting up Signals](/docs/signals/setup) and [How Signals works](/docs/signals/how-it-works). ## Dated verification On August 23, 2026, 195 focused automated checks passed in the main Pathrule product repository. They covered: - Knowledge discovery, import ordering and exclusion of noisy sources. - Worktree setup, dependency sharing, lifecycle and dirty-checkout protection. - Task context fingerprints, stale receipt rejection, bounded preparation and deterministic fallback. - Component discovery, configured boundaries, platform isolation and incompatible variant rejection. - Token identity, mode and property-scope validation. - Design readiness, structural and paint fidelity, exact and heuristic identity, and native-tree degradation. - Signals queue bounds, coalescing, redaction, backoff and failure isolation. The public context-delivery benchmark is separately reproducible at [github.com/pathrule/benchmarks](https://github.com/pathrule/benchmarks). [How we measure](/docs/start/how-we-measure) publishes its method, raw artifacts and mixed results. ## A useful evaluation rule For any Pathrule claim, ask three questions: 1. What evidence enters the decision? 2. What happens when that evidence is missing or ambiguous? 3. Which result is allowed to change or block the work? The contracts above answer all three. That is the difference between a feature description and an engineering claim. ## /docs/start/demo-workspace # Demo workspace Every new Pathrule account opens with a **Demo Workspace**: a read-only sample project that shows what Pathrule looks like in real use, before you connect a single repo. It is pinned at the top of your workspace list and marked with a "Demo" badge. ## What is inside The Demo Workspace is a hand-crafted sample repository tree. Click any node and you see coherent example **memories**, **rules** and **skills** attached at sensible paths, exactly as a real team would author them. The root node shows a fully populated **Summary** dashboard, so the analytics and coverage views are populated from the first second. It is there to answer one question quickly: what does path-scoped team knowledge actually feel like? You can browse the tree, open content, and read the dashboard without any setup. ## Read-only by design The Demo Workspace cannot be edited. Any attempt to change content is blocked with a short notice, and the demo intentionally has **no local folder, no hooks, and no agent binding**, so it never asks you to bind a directory the way a real workspace does. In Workspace Settings every section stays visible, but the controls are replaced with a "not available in Demo Workspace" note, so you can still see what the settings would be for a real workspace. ## Removing it You can dismiss the demo whenever you like. Open Workspace Settings and use **Remove Workspace**. The demo is free, and it never counts against your plan limits or seats, so you can keep it around as a reference or remove it the moment you connect your own repo. The Demo Workspace is available on both Pathrule Web and Pathrule Studio, and existing accounts received it too. When you are ready to use Pathrule on your own code, follow the [Quickstart](/docs/start/quickstart). ## /docs/editions/open-source-core # Open source core Pathrule's engine is open source under **Apache-2.0**. The core, the path-scoped memory, rule and skill engine together with the MCP tool surface, runs on your own machine, for free, with no account. ## What the core is The open core is the same engine that powers Pathrule Cloud, minus the team layer: - The **path-scoped context engine**: the `get_context` retrieval, the router that decides how much context a task needs, and the ranking that picks the right slice for the current working directory. - The full **MCP tool surface** for memories, rules and skills. An AI client sees an identical tool contract whether it talks to the local core or to Pathrule Cloud. - An **embedded local store**. Your content lives in a local SQLite database under `~/.pathrule`, with no server to run and no infrastructure to manage. ## Runs fully local The core indexes, ranks and serves context offline. There is no account to create and nothing leaves your machine. It is the fastest way to feel the path-scoped model on your own projects. ## Semantic search and routing Semantic recall and the LLM router are part of the core, gated on **your own API key** (bring your own key). Add a Voyage or OpenAI key and the core recalls by meaning, locally. Without a key, the deterministic router is the default, so the core still works with zero configuration. ## What Pathrule Cloud adds Pathrule Cloud builds on the same core and adds the team layer: - **Team sync** and shared, reviewable knowledge with role-based access. - **Live activity** and overlapping-write detection across teammates. - **AI curation**: assisted merge, generation and staleness detection. - The **managed backend**, plus the Pathrule Web and Studio apps. Pathrule Cloud is the hosted product and is governed by the [pricing plans](/pricing). Everything the open source core offers stays free, local and account-free. ## Getting started Install the CLI and create a local workspace. See [Install](/docs/cli/install) and the [Pathrule CLI](/docs/surfaces/cli) surface for the local commands, and [Core concepts](/docs/start/core-concepts) for the memory, rule and skill model the core delivers. ## /docs/editions/self-hosted # Enterprise self-hosted Enterprise self-hosted runs the **full Pathrule Cloud product on your own infrastructure**, in your cloud, VPC or on-prem environment. It is the deployment model for organizations that need data residency, a security review, or a procurement path that keeps data inside their boundary. This is an enterprise offering. To start a deployment or a proof of concept, [talk to sales](mailto:hello@pathrule.io). ## How it works Self-hosted is **not a different backend**. It is the same managed Pathrule product, pointed at a **customer-hosted database** instead of ours. It ships as **signed container images** you run with Docker Compose, including the app, the web console and the remote MCP connector. The split is clean: - **Your side (data plane):** your database, your data, your backups, your identity. Everything your team authors stays on your infrastructure. - **Our side (control plane):** licensing and entitlement, the commercial relationship, and the closed source. We never hold your data. ## Identity through your SSO Users authenticate through **your own identity provider** over SAML or OIDC, not through Pathrule-hosted accounts. The first providers we certify are **Microsoft Entra ID, Okta, and Google Workspace**. ## Full team features on your infra Because the deployment runs the complete stack, the team layer runs entirely on your side: **realtime sync, live activity, and overlapping-write detection** all work without traffic leaving your environment. ## AI mode AI features are a toggle: - **Hosted proxy:** use our AI proxy; we meter and bill usage. - **Bring your own key:** point the deployment at your own model provider key, and AI traffic goes directly to your provider. ## Licensing and data safety The deployment is gated by an **entitlement license**, not a live billing dependency at runtime. The design is built so you never lose access to your data: - On license expiry, **writes pause but reads and existing data stay available**. There is never a hard lockout. - If the license service is briefly unreachable, the last valid entitlement is honored for a **grace window** before anything degrades. ## Security and compliance Self-hosted is built for security review: **audit logs**, role-based access control, **signed images with an SBOM**, and data-residency guarantees because the data never leaves your infrastructure. ## Support and upgrades We support the latest and previous major versions, with sequential, customer-triggered upgrades and a backup and restore runbook. Versioning and end-of-life terms are part of the contract. ## Open source instead If you want a free, fully local single-developer setup rather than a hosted team deployment, see the [Open source core](/docs/editions/open-source-core). ## /docs/surfaces/web # Pathrule Web Pathrule Web is the management console for your Pathrule organization. It runs in any modern browser at `app.pathrule.io` and is where you run the team and the account, not where you write knowledge or run agents. Authoring memories, rules and skills, and running Claude Code, Codex, Grok, Kimi, Antigravity and OpenCode, all happen in [Pathrule Studio](/docs/surfaces/desktop), the desktop app, where the path-scoped context is delivered. Web is for everything around that: people, plans and workspaces. ## What Pathrule Web is for - **Organization.** Set up your org profile and settings. - **Members and roles.** Invite teammates, assign roles (owner, admin, member), manage access. - **Plans and billing.** Choose Solo, Team or Business, manage your payment method and invoices. - **Workspaces.** See every workspace with its memory, rule and skill counts and contributors; rename, archive or delete, and export the knowledge as a ZIP. - **Usage and activity.** A dashboard of recent activity and team usage across your workspaces. ## What lives in Studio, not Web Pathrule Web does not read your filesystem, run agents, or author knowledge. Those happen in Pathrule Studio on your machine: - Running Claude Code, Codex, Grok, Kimi, Antigravity and OpenCode on the context layer. - Writing and reviewing memories, rules and skills at the path they belong to. - Source control, MCP servers, scheduled tasks, the terminal and run. Sign in once and the workspaces and members you manage in Web are the same ones Studio uses. ## Common flows - **Invite a teammate:** Open Members, send an invite to their work email, pick a role. - **Upgrade the plan:** Open Billing, pick Team or Business, add a payment method. - **Manage a workspace:** Open Workspaces, find the project, rename or archive it, or export its knowledge as a ZIP. - **Check team activity:** Open the dashboard for recent memories, rules and skills across the org. ## What to read next - [Pathrule Studio](/docs/surfaces/desktop) for the desktop app where you code and author knowledge. - [Quickstart](/docs/start/quickstart) for an end to end first session. ## /docs/surfaces/desktop # Pathrule Studio Pathrule Studio is the native macOS app, and the flagship Pathrule surface. It is where you code with your AI engines on top of your team's context, with the local runtime bundled in. Studio puts Claude Code, Codex, Grok, Kimi, Antigravity and OpenCode in one workspace. Start a thread with any engine, then switch models mid-conversation without losing the context you have built. But Studio is more than a chat window: around it sits a full set of surfaces, a Kanban task board your agents run, a design canvas that turns a sentence into a live interactive design, a force-directed knowledge graph, and scheduled tasks, all drawing on the same path-scoped context. Your team's memories, rules and skills are delivered natively, scoped to the path you are working in, so the assistant knows your conventions before its first move. There is no separate daemon to install: the embedded MCP server, the hook supervisor, the local cache, and the AI client config writers all live inside the app. Those surfaces are composable, not mandatory. A coding-only team can stay in Chat, Tasks, Source Control and the terminal. Design, Signals, Council and schedules appear when the work needs them rather than becoming steps every task must pass through. ## The surfaces Every surface below runs on the same context layer, so the right memories, rules and skills arrive before the first tool call, whichever one you are in. - **Chat.** Run Claude Code, Codex, Grok, Kimi, Antigravity and OpenCode side by side and switch the model mid-conversation. An orchestrated mode lets a conductor model plan a goal, split it into subtasks, and dispatch each to the engine that fits, running in parallel and bringing the results back in one thread. Attach a screenshot, mockup or diagram and Pathrule forwards it as real visual context to any engine that can see. Ask for a brand-new screen and the assistant can build it as a live Pathrule Artifact right in the conversation instead of a wall of code. If a run is cut short by a restart or a lost connection, Studio recovers the session and resumes it. - **[Tasks board](/docs/studio/tasks).** A Kanban board you run with AI. Lay work out as a column of cards, hand any card or column to Claude Code, Codex, Grok, Kimi, Antigravity or OpenCode, and watch it move across the board as it works. A run can use the main checkout or opt into its own branch and checkout. Cards can carry images, pasted or dropped on, handed to the agent as visual context and encrypted end to end just like the card's prompt. Start a card on its own or run a whole column, and follow progress live across your devices. - **[Isolated branches](/docs/studio/isolated-branches).** Run a conversation or a single card in its own git checkout of the repository, on its own branch, so several agents work the same project at once and none of them touches your working copy. Your team's memories, rules and skills follow the checkout, so a parallel agent is not a context-blind one. When the work is done, Source Control merges the branch or opens a pull request for you, and a conflict leaves your working copy untouched. It is opt-in per conversation; the default stays the main checkout. - **[Design canvas](/docs/design/overview).** Describe a screen and Studio builds a real, interactive design you can point at and refine in plain words. Connect screens into a [flow and play it as a prototype](/docs/design/flows), [bring frames in from Figma](/docs/design/figma) with their tokens intact, and [check the built app back against the design](/docs/design/verify) on web, iOS or Android. Export any design to PNG in one step, or hand it straight into chat as a snapshot to ask for the next change. Share a design as a private, zero-knowledge read-only link that anyone can open in the browser, with optional pinned comments that appear live and that you can revoke at any time. On a Team plan, your teammates' designs appear in a private, members-only team library where you can watch them update live and comment on them, all inside your organization. - **Knowledge graph.** The Summary surface has a Graph tab: a fluid, force-directed map of your whole workspace, with every folder node linked to its memories, rules and skills, and memories linked to each other through the connections you write. Zoom and pan, hover a node to light up its neighbours, and let it refresh on its own as your team's knowledge grows. - **Schedules.** Set a task to run on any cadence. Studio wakes up on its own, does the work with the right context in place, and leaves the result waiting for you. ## What else is bundled - **Native context delivery.** The hook supervisor reads the path-scoped slice from the local cache and hands the right memories, rules and skills to the engine before its first action, with no MCP wiring to maintain. - **Knowledge authoring.** Write and review memories, rules and skills at the path they belong to, with team comments and threads on each item. Assistants can propose updates as small edits, an append or a targeted replace, instead of rewriting the whole body. - **Local folder attach.** Bind a workspace to a directory on your machine. The runtime resolves your AI session's working directory to a workspace using that mapping. - **MCP server.** The same MCP tool surface Studio's primary agents use, running inside the app. Cursor, Windsurf and GitHub Copilot connect to that Context Layer through Pathrule CLI. - **Companion file sync.** Writes and keeps the AI client config plus the managed companion files (`CLAUDE.md`, `AGENTS.md`) in sync as content changes, and materializes your skills to disk where each client looks for them. Pathrule marks its own files and preserves any you already had, so your hand-written setup is never clobbered. - **[Dictation](/docs/studio/dictation).** Speak a prompt instead of typing it, with cloud transcription across 90+ languages and an on-device macOS engine behind it. - **The workbench.** Source control, Patterns, MCP servers and extensions, usage and an integrated terminal and run, all around the chat. Chat itself splits into panes and detaches into its own windows when one thread is not enough, and a multi-device stage runs your app next to the conversation. - **Offline, dark and light.** Studio works offline against the local cache and follows your system light or dark theme, on signed, notarized builds. - **Tray notifications and auto updates.** Native OS notifications for suggestions, conflicts and team activity, and background updates applied on next launch. ## The iOS companion A cross-device iOS companion keeps a run in your pocket. [Pathrule for iOS](/docs/surfaces/ios) has the full description. Kick off a task on your Mac and follow it from your phone: the same conversations, memories and rules, with live run state synced end to end so a run keeps going while you are away. When an agent edits a file, the phone shows the actual change inline, added and removed lines, tappable to a full-screen view. You can answer a permission prompt or a question from either device, and a conversation started on the phone continues correctly from the Mac. Every connection between your iPhone and Mac is end-to-end encrypted and your source code never leaves your machine; only your team's knowledge and the live session stream sync. The iOS app is [available now on the App Store](https://apps.apple.com/us/app/pathrule/id6786861213); it is the companion to Pathrule Studio on macOS, so install Studio and sign in with the same account to reach your workspaces and live sessions from anywhere. ## What Pathrule Studio hands off to Web [Pathrule Web](/docs/surfaces/web) is the cloud management console. A few flows live there rather than inside Studio. - Organization profile and settings, including ownership transfer. - Members and roles: invite teammates and manage access. - Plans and billing. - Workspace admin across the org (rename, archive, export) and team usage. ## First run 1. Download from [the macOS app page](/products/macos) and open the app. 2. Sign in through the browser based PKCE flow that launches on first run. 3. Create or pick a workspace. 4. Attach the workspace to the local directory you want it to cover. 5. Pick the AI clients you use. Pathrule Studio writes their configs and registers the hooks. After this, open a thread in Studio or your editor in the attached directory. The right memories, rules and skills arrive in context before the first tool call. ## Coexistence with Pathrule CLI Studio and [Pathrule CLI](/docs/surfaces/cli) can run on the same machine. They share the same local cache and the same workspace attachment table. The first runtime to claim a workspace owns its hook supervisor for that session. If you cannot tell which runtime is active, run: ```bash pathrule doctor ``` The doctor reports which runtime owns the workspace, where the cache is, and whether the AI client configs match. ## When to use Pathrule Studio Use Pathrule Studio when you want to code with Claude Code, Codex, Grok, Kimi, Antigravity and OpenCode on top of your team's context, plan and run work on a board, turn a conversation into a live design, and see your knowledge as a graph, with source control, MCP, schedules, usage, terminal and run in one place. It is the default recommendation for most users on macOS. If you live entirely in the terminal, prefer [Pathrule CLI](/docs/surfaces/cli). To manage your organization, members and billing from any browser, use [Pathrule Web](/docs/surfaces/web). ## What to read next - [Pathrule CLI](/docs/surfaces/cli) for the terminal first runtime. - [The Tasks board](/docs/studio/tasks) for running work as cards. - [Isolated branches](/docs/studio/isolated-branches) for running several agents on one repository at once. - [Design overview](/docs/design/overview) for the design surface. - [Pathrule for iOS](/docs/surfaces/ios) for the phone and watch companion. - [How hooks work](/docs/hooks/how-hooks-work) for what the supervisor inside Studio is doing. - [Quickstart](/docs/start/quickstart) for the first end to end session. ## /docs/surfaces/cli # Pathrule CLI Pathrule CLI is the lighter terminal first surface. It hosts the same MCP server, local cache and hook supervisor as Pathrule Studio, but lives entirely in your shell. It is the supported integration route for Cursor, Windsurf and GitHub Copilot, and it also fits SSH, headless and standalone terminal workflows. It is a first class runtime, not a fallback. The content and MCP contract stay shared, while delivery follows the strongest channel each client exposes: native hooks for Claude Code, Codex, Cursor and GitHub Copilot, and a generated companion file plus MCP for Windsurf. ## What Pathrule CLI owns - **Auth.** Two flows: a browser based PKCE flow for desktops, and a device code flow that works over SSH or on any headless machine. - **Workspace attach.** Bind a workspace to a local directory so the runtime can resolve your AI session's working directory. - **AI client install and sync.** Writes Cursor, Windsurf and GitHub Copilot configs, and can also wire standalone Claude Code and Codex CLI outside Studio. - **MCP server.** Runs locally and is the surface your assistant speaks to. - **Hook supervisor.** Registers the native event profile for hook-capable clients and keeps the same path-scoped selection model as Studio. - **Doctor.** A single command that audits cache, MCP server, hook registration, and AI client integration. - **Scripting.** Every command supports `--json` for stable, machine readable output. ## Happy path ```bash pathrule login pathrule org use my-team pathrule workspace create my-project pathrule workspace attach --path ~/repos/my-project pathrule install claude pathrule install cursor pathrule sync pathrule start pathrule doctor ``` After this, opening Claude Code or Cursor in `~/repos/my-project` will see the Pathrule context section before the first tool call. ## Output modes The CLI has two output modes that you switch between with `--json`. - **Human mode (default):** Structured sections, progress spinners, clear next command suggestions. Designed for someone reading the output. - **JSON mode:** Stable schema for scripts, CI runners, and automation. Every command documents its JSON shape. ```bash pathrule workspace list # human pathrule workspace list --json # machine readable ``` ## Commands that open the browser A few flows are cloud only and open Pathrule Web in your default browser rather than reimplementing the UI in the terminal. ```bash pathrule billing pathrule team pathrule org open pathrule workspace open ``` Each one prints the URL it opened so you can copy it for a remote shell. ## When to use Pathrule CLI Use Pathrule CLI when you work over SSH, when you want to script Pathrule into a CI runner, or when you simply live in the terminal. For a full graphical workbench on macOS, use Pathrule Studio, which bundles the same runtime. ## What to read next - [Install](/docs/cli/install) for install paths and the sign in flows in detail. - [Pathrule Studio](/docs/surfaces/desktop) for the macOS app that bundles the same runtime. - [How hooks work](/docs/hooks/how-hooks-work) for what the runtime hands to your assistant. ## /docs/surfaces/vscode # Pathrule for VS Code Pathrule for VS Code is a native editor surface. It brings the workspace knowledge tree, content editing, and AI client setup inside the editor, so the folder you have open is the workspace and the file you are editing is the path. It is the right surface if you live in VS Code, Cursor, or Windsurf and would rather not install a separate app. It is a focused editor surface, not Pathrule Studio. The same content and hooks are driven from the editor you already use, while the bundled CLI owns external client setup. ## Install Install it from the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=Pathrule.pathrule-vscode), or from Open VSX so Cursor and Windsurf can install it too. From the editor, open the Quick Open prompt and run: ```text ext install Pathrule.pathrule-vscode ``` It is free, and local mode needs no account, so you can start the moment it installs. ## What the extension owns - **Knowledge tree.** A sidebar that shows only the paths carrying knowledge, repo-shaped, with memories, rules, and skills grouped under each path. Content counts appear as badges on tree rows and on the matching files and folders in the built-in explorer. - **Active-file sync.** As you move between files the tree follows the editor to the deepest path that covers the current file, and the status bar shows that path with its content counts. - **Content editing.** Memories, rules, and skills open as ordinary markdown editor tabs. Saving persists through Pathrule, with full editor tooling for free. - **Agent setup.** One command connects your AI clients and injects the path-scoped hooks, the same setup the CLI performs. - **Onboarding.** Open a folder with no workspace yet and the extension walks you from set up to a bound workspace without leaving the editor. - **Doctor.** A single command that checks each client is connected, the hooks are present, and the context server is reachable. ## Local mode and cloud mode The extension runs in two modes behind one user interface, the same split as the CLI and the [open source core](/docs/editions/open-source-core). - **Local mode** needs no account. Initialize a folder locally and your memories, rules, and skills live on your machine. It is the fastest way to start, with the open core engine doing the routing. - **Cloud mode** signs you in and adds the team layer: shared knowledge, live activity across teammates, and the managed backend. The mode is a property of the open folder, not a guess. A signed-in user whose folder is not yet a cloud workspace is offered both creating one in the current organization and initializing locally. Cloud-only actions are hidden, not broken, when a folder is in local mode, so the same extension serves both. ## Editing as markdown tabs Open a memory, rule, or skill from the tree and it opens as a normal markdown tab. Edit it like any file and save to persist the change. If a teammate changed the same item while you had it open, the save does not silently overwrite their work: you are offered to reload, keep a copy of your version, or overwrite with your own. Conflicts surface as a decision, never as lost edits. From the explorer, right-click any file or folder for a Pathrule submenu: browse the knowledge that applies there, or create a new memory, rule, or skill scoped to that path. From a tree item you can copy it as a prompt pointer, view its details, rename, move it to another path, or delete it with an undo. Multi-select supports bulk move and delete, and a fuzzy search spans every title across the workspace. ## Identity shared with the CLI Signing in from the extension uses the same hosted login as the CLI, with your choice of GitHub, Google, or email. The session is shared: signing in here signs the CLI in too, and switching organization in one switches it in the other. One identity across the extension, the CLI, and your AI assistant. ## Connect your AI clients A single Connect AI clients command wires your assistant to Pathrule with no JSON editing. - **Copilot agent mode** is registered automatically for the bound folder. - **Cursor, Windsurf and GitHub Copilot** receive managed entries through the bundled Pathrule CLI. Standalone Claude Code and Codex are also available outside Studio. - **Hooks** are injected through the same pipeline the CLI uses, and the result notification lists exactly what was written. After this, your assistant sees the Pathrule context section for the current path before its first tool call. Run the doctor command at any time to confirm each client is connected and the hooks are fresh. ## Working with your team In cloud mode the tree refreshes live as teammates edit, so shared knowledge stays current without a manual reload. Organization-level work stays on the web: team management, plans and billing, and the cross-workspace overview are reached through deep links rather than reimplemented in the editor. If you started in local mode and want to bring a folder to your team, a single action signs you in, picks an organization, and copies the workspace and its content to the cloud, keeping your local copy as a fallback. ## When to use Pathrule for VS Code Use the extension when you work primarily in VS Code, Cursor, or Windsurf and want the workspace knowledge tree, content editing, and agent setup in the editor that already knows your open folder and active file. It is the no-install path: start in local mode in seconds, and sign in later when you want the team layer. If you want a standalone visual app on macOS, prefer [Pathrule Studio](/docs/surfaces/desktop). If you live in the terminal or script Pathrule into CI, prefer [Pathrule CLI](/docs/surfaces/cli). ## What to read next - [Pathrule CLI](/docs/surfaces/cli) for the terminal first runtime that shares the same identity and hooks. - [Open source core](/docs/editions/open-source-core) for what local mode runs and what Cloud adds. - [How hooks work](/docs/hooks/how-hooks-work) for what the extension hands to your assistant. ## /docs/surfaces/ios # Pathrule for iOS Pathrule for iOS is the companion to [Pathrule Studio](/docs/surfaces/desktop). Work still executes on your Mac; the phone is where you follow it, unblock it, and read what it did. [Available on the App Store](https://apps.apple.com/us/app/pathrule/id6786861213). Install Studio and sign in with the same account to reach your workspaces and live sessions. ## What you can do from the phone - **Follow a live run.** Watch it while it is still going, and see why it stopped without opening your Mac. - **Read the actual change.** When an agent edits a file, the phone shows the diff inline, added and removed lines, tappable to a full-screen view. - **Unblock it.** Answer a permission prompt or a question from either device. A conversation started on the phone continues correctly on the Mac. - **Find your place again.** Search across conversations to get back to the thread where something was decided, and use the navigator to jump straight to a turn instead of scrolling. - **Dictate.** Speak a prompt instead of typing it, with the same [dictation](/docs/studio/dictation) engines as the desktop and an on-device fallback when you are offline. - **Work the board.** Review [tasks](/docs/studio/tasks), read the discussion a card carries, and check schedules: what is queued, when each one next runs, and pause or change it. ## Apple Watch The Watch app covers the moments when the phone is already too much: start a chat with dictation, read and reply to conversations, send a quick reply, and review or act on tasks from your wrist. ## What stays on your Mac Your source code. The phone receives conversations, diffs, todos and turn summaries, not your repository. Everything that does sync is **end-to-end encrypted**: encrypted on the device before upload, with the device's private key held in the iOS Keychain and never exported. Adding a device is an explicit approval, so signing in is not by itself enough to read your encrypted history. The [security page](/security) has the full description of the protocol and the one documented exception, a scheduled task result you explicitly mark team visible. ## What to read next - [Pathrule Studio](/docs/surfaces/desktop) for where the work actually runs. - [The Tasks board](/docs/studio/tasks) for what you are reviewing from the phone. ## /docs/surfaces/remote-mcp # Pathrule Remote MCP Pathrule Remote MCP is a hosted Model Context Protocol server. It gives AI clients that only support cloud connectors access to your Pathrule workspace, memories, rules, skills, snapshots and activity, without installing Pathrule Studio or the CLI. It runs at `https://mcp.pathrule.io/mcp` and authenticates with OAuth against your Pathrule account. Use it when your AI client cannot run a local MCP process over stdio and instead expects a remote endpoint. Source: [github.com/pathrule/mcp](https://github.com/pathrule/mcp). ## What Remote MCP is for - **Cloud-only AI clients.** Clients like Claude.ai, Claude Code remote and Codex remote can only reach a hosted connector. Remote MCP is that connector. - **Same workspace, no install.** Read and write the same memories, rules and skills your team uses through Studio and CLI. - **Workspace bootstrap.** List organizations, create a workspace, fetch the setup brief and write the first round of content entirely over the remote connection. ## Choose a local runtime for hook-time delivery Remote MCP is a cloud connector, so its security boundary excludes the local filesystem and working-directory hooks. When context must arrive from a local cache before the first tool call, use Pathrule Studio or Pathrule CLI. Remote MCP remains the no-install choice for clients that can reach only hosted connectors. ## Endpoints - **MCP endpoint:** `https://mcp.pathrule.io/mcp` - **Registry manifest:** `https://mcp.pathrule.io/server.json` ## Connecting 1. Sign in or create an account at `https://app.pathrule.io`. 2. Create or select a workspace. 3. Point your MCP client at `https://mcp.pathrule.io/mcp`. 4. Complete the OAuth flow to approve workspace access. Once approved, the client can read context and write content against the workspace you selected. ## Tools and security - **Read tools:** list workspaces, get context, read memories, rules, skills and snapshots. - **Write tools:** create, update and delete memories, rules and skills. - **Activity:** snapshots, refresh tasks and activity logging. - **Scopes:** access is gated by OAuth scopes `pathrule:read`, `pathrule:write` and `pathrule:activity`, plus database row-level security and rate limiting. ## When to use Remote MCP Use Remote MCP when your AI client only speaks to a hosted connector, or when you want workspace access from a machine where you have not installed Pathrule. For local hook execution and repo-aware context, use the Studio or CLI surfaces instead. ## What to read next - [MCP overview](/docs/mcp/overview) for how Pathrule exposes its tools. - [Pathrule Web](/docs/surfaces/web) for the browser control center that shares the same cloud. - [Quickstart](/docs/start/quickstart) for an end to end first session. ## /docs/studio/tasks # The Tasks board The Tasks board is a Kanban board your agents work. You lay out cards in lanes, hand a card or a whole lane to an engine, and watch the work move across the board. A card can opt into its own branch and checkout when isolation is useful; otherwise it runs in the main checkout. The choice is visible on the card rather than hidden in a board-wide default. Cards carry what a person would need to start: a prompt, and images you pasted or dropped in, which are handed to the agent as visual context and encrypted end to end just like the prompt text. ## The lanes Lane headers show a progress mark in the lane's status colour, empty, quarter, half, or full, followed by the task count. Each lane has an add control and an overflow menu that can add a card, move every card elsewhere, sort by newest, oldest, or alphabetically, or delete every card with a confirmation. Sorting is a view, not a rewrite: it does not mutate the persisted card order. ## Context is prepared for you There is no "prepare context" button, no "run anyway", and no readiness dialog to dismiss. Before a card runs, Pathrule assembles the context that card needs, and the run starts with it in place. The reason this is autonomous rather than a step you confirm is that a confirmation on a background board is just a queue of stale dialogs. Preparation is claimed atomically, so two runs cannot prepare the same card twice, and the result is a receipt you can read after the fact rather than a prompt you had to answer before. ## The Agent Command Center Autonomous work is only acceptable if it is legible. The Command Center shows the live stages of a run and then a factual receipt of what it used: - Which Pathrule memories, rules, and skills went in. - Which files were touched. - Tokens and cost. It reports; it does not add another set of buttons to press. ## The learning loop When a run succeeds, it is reviewed deterministically, exactly once per conversation. The review costs no extra model call. What it produces is **proposals**: a memory worth keeping, a rule that should have existed, a skill that would have shortened the run. Lasting knowledge changes stay proposal-first, so the board can learn without quietly rewriting your team's context while nobody is looking. ## Running a card in an isolated branch Any single card can be run in [an isolated branch](/docs/studio/isolated-branches): its own branch and its own checkout of the repository, so the agent works without touching your working copy. It is a per-run action on the card rather than a board setting, so the default stays the main checkout, and a card that ran isolated carries the branch and the base it ran on. When the work is done, the branch is merged or opened as a pull request from Source Control. ## AI activity levels AI activity has three levels: - **Low** stays deterministic. - **Medium** is the default and the balanced setting. - **High** does more per run. Medium and High are both bounded by the same rolling-token policy and by the workspace maximum, so a member cannot raise their own level past the ceiling an admin set, and no level escapes the hard usage limits on the plan. The level is set from the Tasks settings menu. ## What to read next - [Isolated branches](/docs/studio/isolated-branches) for running a card, or a chat, on its own checkout. - [Pathrule Studio](/docs/surfaces/desktop) for the surfaces around the board. - [Writing memories](/docs/content/memories) for what the learning loop is proposing. - [Pathrule for iOS](/docs/surfaces/ios) for following a run from your phone. ## /docs/studio/isolated-branches # Isolated branches Two agents on one repository used to overwrite each other. Turn isolation on for a conversation and it gets its own branch and its own checkout of the repo: the agent edits, installs and tests in there, and your working copy is never checked out, never stashed and never touched. Several agents can run on the same project, each on its own branch. Isolation is opt-in per conversation. The default stays the main checkout, so if you never reach for it, nothing about a normal session changes. ## Arming it in the composer The control is a chip in the composer, next to the engine and mode pickers, because "should this run on its own branch" is the same kind of decision as "which model". There is no launcher to walk through and no extra step in starting a chat. Two things follow from where the chip sits: - **Arming cuts the checkout immediately**, while you are still typing, and dependency preparation starts there too. Cutting a checkout and preparing a monorepo takes real seconds, and the worst possible place to spend them is between pressing enter and the agent starting. By the time you send, the branch exists. - **The chip locks after your first message** and becomes the branch badge. An engine's working directory is fixed when its conversation is created, so a control that still looked editable would be lying to you. Branch names are always English, even when you write your request in another language, and they follow the convention your repository already uses rather than imposing one, with a namespace per engine so it is obvious where a branch came from. The name is derived from your first message in the background, while the agent is already working, so naming never delays anything. If no model is reachable the branch keeps a neutral English name instead of the session failing. ## A parallel agent is not a context-blind one An isolated checkout lives outside the folder your workspace is bound to. Taken naively, that means an agent working in it resolves to no workspace at all: no memories, no rules, no skills, and every working-directory-bound tool call failing. Isolation would have made Pathrule blind inside its own feature. So Pathrule resolves an isolated checkout back to the workspace it was cut from. A parallel agent receives exactly the same path-scoped context as an agent in the main checkout, delivered the same way, [before its first tool call](/docs/hooks/how-hooks-work). Extra checkouts you cut by hand before any of this existed can be adopted, so they stop running without context too. This is the part that does not come for free with a git command. Isolation is a checkout; keeping the knowledge layer attached to it is the product. ## A checkout the agent can actually build in A fresh checkout carries no installed dependencies and none of your ignored files, so on most real projects an agent would land somewhere it cannot install, build or test. Studio closes that gap, and asks first: - It reads your lockfile, names the exact command it would run (`pnpm install --frozen-lockfile`, `npm ci`, `yarn install --immutable`, `bun install --frozen-lockfile`), and lists the ignored files it would copy across, typically `.env` and `.env.local`. - You answer once per project: **Skip**, **Run once**, or **Always**. On Always, later sessions in that project prepare silently. No command is ever run in your repository before one of those two answers. - Preparation state is visible on the conversation while it happens: preparing, ready, failed, or skipped. A failed preparation keeps the checkout and its output, because that output is the only diagnosis you have. When the lockfile in the new checkout is byte identical to the one in your main checkout, Studio borrows the prepared dependency tree instead of installing a second one. It prefers to **clone** it, so the tree belongs to that checkout: an install you run there does not reach your other sessions. On a filesystem that cannot share blocks it falls back to a symlink, and then the consent line says "shared" out loud, because an install run inside one session is visible to the others. If borrowing is not safe at all, a dependency bump or a different base branch, it installs properly instead. ## What a checkout actually costs A prepared isolated checkout costs about what your tracked sources weigh, and almost nothing for dependencies. Measured on two projects on the same machine (macOS, APFS, August 24 2026): | Project | Tracked sources | Dependencies | Prepared checkout | | --- | --- | --- | --- | | This monorepo (pnpm, 5147 files tracked) | 83 MB | 9 MB | **92 MB** | | A Next.js app (npm, 45824-entry tree) | 11 MB | 17 MB | **28 MB** | Ten parallel isolated sessions on this monorepo therefore cost roughly 0.9 GB. Your git history is not part of that: a worktree shares the main repository's object store, so this repository's 361 MB of history is not copied even once. Three things make those numbers what they are. **Copy-on-write.** A directory walk reports 1392 MB for the same monorepo checkout. It is not lying about the files; it is counting shared blocks at full size. Where the package manager imports from a global store, those bytes exist on disk once. Studio measures the free-space delta around each create and each removal instead of walking the tree, and records "not measured" rather than a zero when a reading cannot be separated from other disk activity on your machine, so a walked figure is never treated as the space a cleanup would return. **Cloning the prepared tree.** Not every package manager shares blocks on its own: on the same volume, an npm project's tree cost 684 MB to install where the pnpm one cost 9 MB. So Studio clones the prepared tree into the new checkout, which measured 17 MB for that 45824-entry tree. The clone is checked rather than trusted: every entry present, relative `.bin` symlinks intact, binaries running from it, and a write inside it leaving the original file untouched. **Measuring, not guessing, whether the disk can do it.** A clone-preferring copy onto a filesystem that cannot clone quietly performs a full copy and still reports success, so Studio writes a small probe and reads the volume. An answer it cannot trust counts as unknown, which falls back to the shared symlink rather than committing you to a full copy. One thing worth knowing, because it tells you where to look if a checkout ever does get large: the dependency tree is not what grows. Divergence is. Once an agent builds, shared blocks are rewritten into real bytes, and build outputs in this repository's main checkout measure about 343 MB against a 9 MB dependency install. So clearing build output reclaims space and clearing dependencies does not, which is the opposite of what the folder sizes suggest. Skipping is a legitimate answer. The agent can still read and edit; it just cannot install or test, and the conversation says so rather than letting you find out from a confusing failure. ## Seeing what the isolated agent did Isolation without visibility reads as "the agent did nothing". Source Control gains a checkout switcher: pick a checkout and the file status, the per-file diff, staging, commit, the branch menu and push all operate on that one. There is a single changes view rather than a second surface to keep in sync with the first. You can also open a terminal in a checkout or reveal it in Finder. ## Watching several at once Tabs stop working as the only view when several agents are running, so the chat splits into panes and each pane carries its own identity: the branch, the engine, and what that session is doing right now. A session waiting on a human gets an accent ring, an icon and a "needs you" label, because the bottleneck is often the one blocked on an answer. Colour alone would not carry that. Panes are deliberately not reordered when a session starts waiting. You built that layout by dragging; moving panes under you is a worse problem than the one it would solve. ## Landing the work This is where isolation stops being a parking space. A landing bar sits under the changes list, and one explicit action takes the branch home. - **Merge** into the base, as a squash, a fast-forward, or a merge commit. Squash is offered first: agents produce a lot of small commits, and your history probably does not want all of them. - **Pull request**, pushed and opened for you. The agent may draft the title and body from its own work; you edit them and press the button. Draft PRs are one toggle. Everything here is executed by the desktop, never by the model: Studio runs `git` and `gh`, and an engine is never asked to do it instead. That has consequences worth stating. - A checkout with uncommitted changes is refused with the reason, not merged half way. - **A conflict stops and leaves your working copy untouched**, naming the files that conflicted. Pathrule reports a conflict; it does not resolve one for you. - If `gh` is missing or not authenticated, the error names the missing tool. There is no silent fallback. - After a successful merge, Studio asks whether to remove the checkout and reclaim its disk. It never deletes silently. Nothing lands automatically. There is no flow in Pathrule that merges an agent's branch without you pressing something. ## Lifecycle, disk and privacy **A conversation and a checkout are separate things.** Closing a conversation leaves its checkout and its branch alone, because the work in there may still be the thing you care about. Removing a checkout warns you about uncommitted changes with the count, and asks separately whether the branch should go too; by default the branch is kept. Checkouts live in one predictable place, `~/Pathrule/worktrees` by default and configurable, outside your repository. That is deliberate: nested copies of a project would be walked by every file watcher, project scan and index you have, and one folder is what you can exclude from a backup or clear out in a single action. Housekeeping stays conservative, and it now covers the one checkout that actually accumulates: the one whose branch already landed. A landed checkout keeps its owner, so it used to sit there until you answered the offer above. But once a branch is in your base, everything left in its checkout is either tracked, and so already in the base, or ignored, and so reproducible. Studio reclaims it, and only when all of these hold: - **The work landed.** Two separate ways of knowing, because neither covers the other. Studio's own record covers a landing it performed, including a squash merge, which rewrites your commits so they stop being ancestors of anything. Asking git covers a landing Studio never saw: a merge you did in the terminal, a pull request merged in a browser, a teammate's push. The question is not "did Studio merge this" but "is there anything here your base branch does not already have". If git cannot answer, the checkout stays. - **Nothing is using it.** An engine's working directory is fixed for its conversation's life, so a merge does not end the isolation. A landed checkout can still be where a live conversation is running, and that one is never touched. This covers Tasks too: a card's run creates a conversation, so the same question answers both. - **A grace period has passed**, because landing is not the same moment as being done looking at the work. A day by default. - **`git status` is clean.** An ignored build artefact is reproducible; a tracked change is your work. This is why a checkout holding gigabytes of dependencies still counts as clean, and why one holding an uncommitted edit never gets swept. - **Studio created it.** A checkout you added by hand is adopted, and adopted checkouts are never removed automatically. The branch itself is left alone. Reclaiming a folder Studio created is housekeeping; deleting a branch is a decision about your history, and nothing automatic makes that decision for you. The older rules still apply too: a clean checkout that was armed and never claimed goes after an age guard, and records whose folder is gone are pruned. And the safety net underneath all of it is unchanged: if a checkout disappears from under a conversation, that conversation reopens on the main checkout and tells you so rather than silently relocating the agent. Housekeeping is meant to be something you never think about, so it runs in the background rather than as a screen you tend. What it does is still recorded rather than assumed: the measured bytes it reclaimed, and separately the removals it could not measure, because "reclaimed nothing" and "could not tell" are different facts and only one of them is a number. Checkout records stay on your machine and are never synced to your teammates. Paths are machine specific, and a preparation command is a shell command: a synced record would let one person's setting run on another person's laptop. ## Tasks cards can be isolated too On the [Tasks board](/docs/studio/tasks), "run in an isolated branch" is a per-run action on a card rather than a board setting, so the default stays the main checkout there as well. A card that ran isolated carries the branch and the base it ran on, and shows them on its face. If cutting the checkout fails, the run continues on the main checkout with the reason reported instead of dying over bookkeeping. Parallel board runs appear in the same checkout list as chat sessions, so there is one place where every extra checkout on the machine is visible. ## What to read next - [The Tasks board](/docs/studio/tasks) for running a card on its own branch. - [Pathrule Studio](/docs/surfaces/desktop) for the surfaces around the chat. - [How hooks work](/docs/hooks/how-hooks-work) for what reaches an agent before its first action, isolated or not. ## /docs/studio/dictation # Dictation Some prompts are faster said than typed, especially the long ones that describe a bug. Dictation records while you hold the control, transcribes the clip, and drops the text where you were about to type. Nothing listens in the background, and there is no always-on microphone state to forget about. ## Two engines - **Cloud (default).** Covers 90+ languages, handles domain vocabulary, and can drop filler words and false starts so a spoken sentence arrives as a written one. Terms from your workspace, product, package, and repository names, are sent with the request so the model spells them the way your team does. - **On-device (macOS).** Covers 22 languages and runs entirely on your machine. It takes over when the cloud path is unavailable, when the weekly allowance is spent, or when cloud dictation is turned off for the installation. A language the on-device engine does not support stays on the cloud path even past the allowance. Falling back to an engine that cannot speak the language would end dictation rather than lower its quality. Studio tells you once when the engine changes, not once per clip. ## The allowance Cloud transcription is metered in **seconds of processed audio**, not requests, and the pool belongs to the organization: per-seat minutes multiplied by paid seats, spent from one bucket, reset weekly with no roll-over. | Plan | Cloud dictation per seat, per week | | --- | --- | | Solo | 15 minutes | | Team | 60 minutes | | Business | 120 minutes | | Enterprise | Uncapped | Pooling is deliberate. A strict per-user cap wastes most of a team's allowance while the two people who actually dictate hit a wall, at identical provider cost. Two details that follow from metering audio rather than requests: - **Duration is derived from the audio server-side**, so a client cannot under-report what it used. - **A failed provider call is counted for diagnostics but never billed**, because you did not receive the result. ## Privacy On the on-device path the audio never leaves your machine. On the cloud path the clip is uploaded to a Pathrule Edge Function, forwarded to our speech provider for transcription, and dropped once the transcript comes back; we keep the transcript as your own content and the number of seconds, not the recording. The clip exists on disk only as one temporary file, deleted immediately after the call. Cloud dictation can be disabled for a whole installation with `PATHRULE_CLOUD_SPEECH_DISABLED=1`, which self-hosted deployments and organizations with a no-third-party-audio policy can set. There is no per-user provider switch. The provider is named in the [Privacy Policy](/privacy-policy). ## What to read next - [Pathrule Studio](/docs/surfaces/desktop) for the surface dictation lives in. - [The Tasks board](/docs/studio/tasks) for dictating a card instead of a chat message. ## /docs/studio/plugins # Plugins A plugin is a packaged capability you connect once and then have everywhere. Connect Linear, and the tools it brings are written into every AI engine on your machine, not just the one you happened to be using when you clicked. ## Four objects, and why the difference matters Two of these look alike from a distance, so the distinction is worth stating plainly. | Object | What it gives you | Where it lands | Who owns it | | --- | --- | --- | --- | | Plugin | a capability: tools, skills, agents | your engines' config files and skill directories | the author or the catalog | | Pattern | knowledge: memories, rules, skills | your Pathrule tree, at a path | you, from the moment you import it | | MCP server | one tool surface you configured by hand | the config line you wrote | you | | Agent | a subagent definition | your agent directory | you, or a plugin | The carrier of the distinction is not the content, it is **ownership**. A plugin's skill is updated upstream by whoever publishes it. A pattern's skill becomes your knowledge the moment you import it, and it never changes underneath you again. The same thing can arrive by both routes, and that is the difference. A single MCP line you typed yourself is not a plugin. It stays in its own group, and it keeps its own menu. ## The Plugins panel One scroll, three sections, and one row per thing you can manage on its own. ``` PLUGINS 4 1 needs attention Drive GLOBAL Connected Notion GLOBAL Sign in again Supabase PROJECT 5 tools Vercel GLOBAL 3 tools, 1 agent MCP SERVERS 2 postgres PROJECT Connected AGENTS 2 code-reviewer PROJECT ``` The rules the panel is built on: - **A row is something you can remove or switch off by itself.** A plugin is one row even when it carries five tools, and the MCP server a plugin brings never appears in the MCP SERVERS group, because you do not manage it separately. - **A row carries identity and state, never an inventory.** What a plugin contributes is a question about one plugin, so it lives on that plugin's page, named rather than counted. Pressing a row goes there. - **Order is stable, always.** Floating a broken row to the top would move the thing under your cursor between renders. - **The row menu teaches the type.** A plugin offers Update, Disable and Remove. A server you configured by hand offers Edit JSON, Auth, Disconnect and Delete. The asymmetry says what kind of thing you are looking at without a word of explanation. - **A badge is only ever an action you need to take**: an expired sign-in, a server that will not connect. "A new plugin is available" is never a badge. ## The Marketplace Discovery is a tab in the main layout rather than a modal, so it is independent of whether you were in Chat, Tasks or Design when you opened it. It has two tabs of its own, Plugins and Patterns, because they are the two things you can bring into a workspace. Sections group the catalog and the section header opens the whole category. A card shows a logo, a name and one line of promise. What a plugin is made of and where it came from live on its page, not in the list, because a composition line does not separate two rows and this list exists to be scanned. ## Installing writes to every engine This is the part that is easy to miss and the reason plugins exist as their own object. When you connect a plugin, Pathrule first writes it into the configuration of every Studio agent you have installed: Claude Code, Codex, Grok, Kimi, Antigravity and OpenCode. Pathrule CLI then carries the same plugin into Cursor, Windsurf and GitHub Copilot when you use those external integrations. Each agent keeps its MCP configuration in a different file, format and location. Pathrule knows all of them. Skills the plugin ships are written into each engine's own skills directory, and duplicate targets are filtered so a skill is never written twice for engines that share a directory. At install time you choose the scope: - **Global**, for every project on this machine. This is the default, because an account connection like Drive or Notion is meaningful at the machine level. - **This project**, for one workspace. Engines with no project-level configuration fall back to global and show up as GLOBAL in your inventory. That is a quiet, correct fallback rather than an error you have to read. ## Permissions remain engine-native Connecting a plugin does not give an agent new permissions over your machine. The tools it brings run under the engine's own permission model, and the rules and work-safety limits described in [Rules as guardrails](/docs/hooks/rules-as-guardrails) and [Work safety](/docs/hooks/work-safety) still apply. ## /docs/studio/simulator # Simulator Studio can run your iOS or Android app in a simulator inside the app, and an agent can drive it. Not screenshot it, drive it: tap, swipe, type, scroll, wait for a screen and read what is on it. That turns "it builds" into "it works", and it is what makes a design prototype checkable against the running app rather than against a description of it. ## The session A simulator session belongs to a workspace and a platform. You start it from the launch target Studio detects in your project, and it opens as a floating device frame you can move, resize and put away without ending the session. Starting one is gated on the folder you approved. The gate resolves the launch target back to a workspace root you actually opened, so a monorepo whose app lives in `apps/mobile` works from the workspace root you picked, and a case-insensitive filesystem does not turn one directory into two different answers. ## What the agent can do The agent reaches the simulator through a small, enumerable set of tools: - **observe** and **screen state**, to read what is on screen right now. - **find**, to locate an element by accessibility identifier or by label. - **act**, for a tap, a swipe or a full touch path with per-sample timing. - **batch**, for a sequence of actions run as one step. - **wait**, for a screen or a condition. - **run app**, **record screen**, **status** and **stop**. There is no "type anything into the device" primitive that bypasses this list. What the agent can do is what these tools do. ## You and the agent share one device Both of you can touch the same simulator, so something has to decide who is driving at any moment. An input arbiter owns that: it tracks whether the current owner is you (a window and a pointer) or the agent (a thread, a turn and an action), and it hands control over cleanly rather than interleaving two streams of taps into one confused gesture. In practice this means you can take the device back mid-run by touching it, and the agent's next action queues rather than fighting your finger. ## Where it is used **Checking a design against the running app.** A prototype in the Design surface is a graph of screens and transitions. Pathrule compiles that graph into simulator actions and runs it, so the flow you drew is executed against the real app. See [Verifying a design against the running app](/docs/design/verify). **Finishing a task honestly.** A card that changes a screen can end with the agent opening the app and looking at it, instead of ending at "the code compiles". ## Requirements An iOS session needs the platform's own simulator tooling installed and a target Studio can launch. Studio checks for that before it offers to start a session, and it tells you which piece is missing rather than failing at launch. ## /docs/studio/schedules # Schedules A schedule runs a brief on a repetition. Every run is kept, and every result lands in one place you can read later. You do not fill in a cron expression. You ask for it in chat, or you open Schedules and describe what should happen and when. ## What a schedule can be about A schedule stands on one of three subjects, and the subject decides where its results go. - **On its own.** A standing brief with no other object attached. "Every weekday at nine, summarise what changed in the repository since yesterday." Results collect in the schedule's own history. - **A task card.** The card is re-run on the repetition, and every result is collected on that card. This is how a recurring check becomes part of the board rather than a separate stream you have to remember to read. - **A design.** Each run lands on that design's plane, so a recurring brief can keep producing work into the same canvas. The design shows that it is fed by a schedule, so nobody wonders where the new frames came from. ## Every run is a conversation A scheduled run is not a log line. It streams into a real conversation you can open, read and continue, exactly like a session you started yourself. That is the difference between a job that ran and work you can inspect. ## It refuses to start work it cannot finish Agents run against a quota that resets on a clock. A scheduled task that starts with thirty minutes of headroom and needs two hours does not produce a useful result, it produces a truncated one. So before a run starts, a quota gate compares the headroom you have left against the reset time and what this task has historically needed. If it clearly will not fit, the run is **deferred to the reset** and you are told, rather than being quietly downgraded to a weaker engine to squeeze it in. A task that has never run before is not deferred. It runs untimed the first time, because the honest thing to do with an unknown is measure it. ## On every surface Schedules are not a desktop feature with a mobile viewer. They exist as their own surface in Studio, in the browser, and in the iOS app, because the moment you most want to check whether last night's run produced anything is rarely the moment you are at your desk. See [Pathrule for iOS](/docs/surfaces/ios) for what the phone can do with them. ## /docs/studio/board-settings # Board settings The board has four settings, and each one is a decision about how much a board full of agents is allowed to do without you. ## Parallel runs Off, Run All works one group at a time. On, it runs groups at the same time. What makes that safer is separation. Before anything starts, Pathrule predicts which files each group of cards will touch. Groups that touch **different** files run simultaneously, each in its own git worktree. Groups predicted to touch the **same** files are merged into a single sequential lane, which prevents known collisions from becoming two edits in one checkout. The prediction is not treated as proof. A board of ten cards is not ten independent jobs, and a plan can miss a file it later needs. Separate worktrees keep a missed prediction isolated as branch work rather than two agents overwriting one folder. Landing still stops on a real merge conflict. ## Auto plan On, every new card gets a detailed plan generated in the background, before you ask for one. A plan moves through visible states: queued, planning, awaiting reply, ready, or failed. "Awaiting reply" is the honest one. If the planner needs something only you know, it stops and asks rather than guessing and producing a confident plan built on an assumption. A card with a ready plan starts from a plan instead of a sentence, which is most of the difference between a run that lands and a run that wanders. The plan is scoped to one card. It has a goal, ordered steps, a test path and risks. Context preparation separately fingerprints the current card revision, resolves target paths and can record a dependency or conflict gap. If the card changes, a stale context receipt is rejected instead of being handed to the run. ## AI activity Pathrule prepares context autonomously. This setting controls one narrower thing: when a bounded model pass is allowed to resolve material ambiguity in that preparation. - **Low, deterministic.** Uses Pathrule and path coverage, with no model calls at all. - **Medium, balanced.** The default. Limited model help, only for material blockers. - **High, proactive.** Resolves more ambiguity on its own, inside the same hard budget. High is not "spend more". The budget does not move between levels; what moves is how much ambiguity the preparation is allowed to settle before it hands the card to an engine. Usage is shown as it is spent: model passes today, and rolling tokens, both against their limits. ## Workspace maximum An account default sets the level for your workspaces, and a workspace can set its own maximum on top of it. If your personal choice is above the workspace maximum, your choice is **capped** rather than overridden silently. The setting shows the level you picked, the effective level you are actually getting, and the fact that a workspace ceiling is what reduced it. A ceiling that lowers your setting without saying so is a setting you cannot trust. This is what makes a shared board predictable: an organisation can decide how autonomous preparation is allowed to be, and every member sees that decision rather than discovering it. ## /docs/studio/summary # Summary and the knowledge graph Summary is the surface that answers "what is actually in this workspace, and what has it been doing". It is the one place in Studio that looks at the whole thing rather than at the work in front of you. ## What it shows Two independent column stacks, so every card is the size of its own content rather than stretched to match a neighbour: - **Context injection over the period**, and what it consisted of: how many rules were surfaced, how many memories, how many risky actions were stopped before they ran. - **The knowledge base**, counted by kind, with what changed this month. - **Activity over time**, with its peak marked, because the shape of a month is the thing a number cannot say. - **A domain and action matrix**, so you can see where the work happened rather than only how much of it there was. - **Contributors**, and what each person has taught the workspace. There is no readiness score and no health gauge. A single invented number that grades your workspace is a number nobody can act on. ## The knowledge graph The graph is the workspace as a shape: every memory, rule and skill as a node, and the links between them as edges. Paths pull their own knowledge together, and an item that a dozen unrelated things depend on looks different from one that stands alone, because it is drawn differently. It is the fastest way to see two things that a list cannot show you: - **Where the knowledge is dense**, which is usually where the product is complicated. - **What is isolated**, which is usually something that was written once and never connected to the work it was about. Selecting a node previews it in place, so you can move through the graph without leaving it, and filters narrow the graph by kind of link rather than hiding nodes at random. The renderer is built once and paused when you leave the tab, so opening the graph does not cost you anything for the rest of the session. ## /docs/studio/pathrule-auto # Pathrule Auto Auto is one thing you pick instead of a decision you make every turn. Select it once and Pathrule chooses which engine and which model runs each message. ## It routes over what you already pay for This is the part that separates it from a per-prompt API router. Auto does not send your work to a catalogue of hosted models billed by the token. It routes over the **local, subscription-limited engines you already have installed and signed into**: the same Claude Code, Codex, Grok, Kimi, Antigravity and OpenCode you would have picked by hand. So the resource it is being thrifty with is your existing plan, not a new bill. ## Sticky on purpose A stateless router picks the best model for each prompt in isolation. That works when a prompt is a prompt. It does not work here, because switching engine mid-conversation is a real **context handoff**: the new engine has to be given the thread rather than simply continuing it. So Auto is deliberately sticky. It stays on the engine already driving the thread, and leaves only when that engine is genuinely no longer an option: its limit is reached, you signed out, or it is no longer installed. Even then it does not move for a small difference. Another engine's best option has to beat the current one by a real margin before Auto pays the cost of a handoff, which is what stops it flip-flopping between two nearly equal choices and losing the thread's continuity each time. ## Models change every turn, engines do not Inside one engine, changing model is cheap: it is an override on the next turn, with no handoff at all. So that is where Auto does most of its work. Each turn is read for what it actually needs: - **Complexity**, from trivial to hard. - **Vision**, when the turn carries images only a multimodal model can read. - **Long context**, when the assembled context is large enough to need a big window rather than a fast one. A cost and quality dial decides how those needs are weighed, and it leans thrifty by default: a trivial turn does not get the expensive model just because it is available. ## A small pool, on purpose Auto chooses from a curated set rather than the full model picker: roughly a cheap, a middle and a strong rung per engine. A router that can reach forty models produces choices nobody can explain; one that reaches nine or ten produces choices you can predict. One deliberate omission is worth stating: a model that would bill to usage credits rather than run inside your plan's limits stays out of the pool, even when it is technically available to your account. Auto is not allowed to spend credits you did not agree to spend. Picking that model stays a manual choice. ## Where it applies Auto is not only a Chat setting. The same policy runs in the Tasks board, in [scheduled runs](/docs/studio/schedules), and in work drained from another device, so a card that runs while you are asleep makes the same choices you would have got in front of the app. ## /docs/studio/multiple-agents # Several agents at once Chat is not one session. It is a set of tabs, and each tab is its own agent. ## One workspace, several engines Open a tab for Claude Code, another for Codex, another for Grok. They run at the same time, on the same workspace, each with its own conversation and its own run state, so the tab strip tells you which ones are working and which are waiting on you. They run under **your** subscriptions, on the engines you already installed. Pathrule is not reselling model access; it is running the tools you already have, side by side. ## They all start from the same knowledge This is the reason running two engines is useful rather than just noisy. Every tab receives the same path-scoped memories, rules and skills for the path it is working in. So a second opinion is genuinely a second opinion: another engine reading the same context and the same constraints, not a fresh session you have to explain your product to again. ## Tabs survive a workspace switch Open tabs are tracked above the workspace they belong to. Switch to another workspace and its own tabs appear; switch back and yours are still there, still running. A long job does not end because you looked at something else. ## Parallel work without collisions Two agents editing one repository is a merge accident waiting to happen, so parallelism is paired with isolation: any session can run in [its own branch and its own checkout](/docs/studio/isolated-branches), which is what makes "several agents at once" a working arrangement rather than a race. On the Tasks board the same idea is automatic: [parallel runs](/docs/studio/board-settings#parallel-runs) put groups that touch different files in separate worktrees and merge colliding groups into one sequential lane. ## Or let Auto decide If you would rather not pick, [Pathrule Auto](/docs/studio/pathrule-auto) chooses the engine and the model for you, and stays on one engine per thread because moving is a real context handoff. ## /docs/studio/council # Council Some turns deserve more than one opinion. Council sends a single chat turn to several models at once, then hands you one answer. ## Ask a turn to several models Type `/council` and it arms your next message. Write the request as you normally would, and instead of one engine replying, several do, at the same time. It runs in place. No new tab opens and the thread keeps its own model. The council does its work behind that one turn, and the synthesized answer streams into the same conversation as the reply. ## They cross-check each other The members are anonymized, shown as Member A, Member B and so on rather than by engine or model. When cross-review is on, each member reads the others' answers with the names hidden, ranks them by accuracy and insight, and cannot reveal or guess who wrote which. That anonymity is the point: an answer wins on its merits, not on which model it came from, and a single model's blind spot is less likely to survive contact with the others. ## Your chat model has the final word The chairman is your thread's own model. It already holds the full conversation and the voice the thread has been speaking in, so it is the one that reconciles the disagreements, keeps what is strongest, and writes a single reply in that voice. It does not paste the members' answers back to you or name them; it synthesizes. ## The same context, several readings Each member starts from the same path-scoped memories, rules and skills for the path you are working in, plus a brief of the conversation so far. So a council is several engines reading the same product knowledge and the same constraints, not several sessions you would have to explain your product to one by one. ## Advisory by design Members are told, in plain terms, not to modify any repository files. Council is for a decision rather than a change: an architecture call, a tricky trade-off, a design someone wants sanity-checked, a review before you commit to a direction. When you want the work actually done, that is what [Workflow](/docs/studio/workflow) is for. ## From the engines you already have The members are the local engines you already installed and signed into, running under your own subscriptions rather than a hosted catalogue billed by the token. Readiness is checked first. An engine that is not both installed and authenticated cannot take a seat, so it is substituted with the next ready engine or, if none remain, the seat is dropped and surfaced to you rather than silently missing. Below two usable members there is no council to run, so the turn falls back to a single normal answer with a note that it did. ## /docs/studio/workflow # Workflow A hard request is often several smaller jobs. Workflow lets one turn plan itself, split into parallel work, and come back as a single result. ## One turn, orchestrated Type `/workflow` and it arms your next message. The run happens in place, in the current thread, and your chat's own model becomes the conductor: it reads the request first and decides how much orchestration the work actually needs. ## Plan, fan out, come back The conductor breaks the request into independent sub-tasks and runs them as parallel workers, each on its own engine, so a job that would have been one long sequential turn becomes several short ones happening at once. Up to four run at a time. As they return, the conductor checks each result and assembles the answer from what came back. You can leave the routing to it or pin a sub-task to a specific engine, so "one Claude and one Codex on this" is a thing you can ask for rather than hope for. ## It decides how far to go Not every request needs a swarm, so the conductor picks a mode for the run: - **Answer directly**, in one turn with no workers, when the request does not warrant them. - **Investigate and reply**, when it is a question: the workers dig, the conductor writes the answer, and nothing in your repository changes. - **Propose and integrate**, when it is code: the workers draft the change and the conductor folds it into the project. Writing to the repository is always an explicit decision, so by default a workflow answers rather than edits. ## Workers read, the conductor writes Each worker runs in its own isolated scratch space and may read your repository but not change it. Only the conductor writes to the real project, it leaves the change unstaged so you review it before anything is committed, and it never runs git on your behalf. If a worker fails, the conductor is the one that retries it, within a bounded number of passes, rather than letting a worker try to heal itself. A run also has a cost and step ceiling, and when it reaches one it stops and hands back what it has rather than running on. ## Grounded in the right context Each worker boots from the path-scoped memories, rules and skills for the path its sub-task belongs to, plus a brief of the conversation so far. A parallel agent is not a context-blind one: it reads the same product knowledge a normal turn would, scoped to the work in front of it. ## The same engine behind the board Workflow is the same conductor that runs a whole [Tasks board](/docs/studio/tasks) when you run it all at once. There, cards are clustered by what they touch, and groups that touch different files run in [parallel git worktrees](/docs/studio/board-settings#parallel-runs) with a branch each, while groups that would collide are merged into one sequential lane. ## Council's sibling Workflow does the work. When you want several opinions on one question instead of one answer, that is [Council](/docs/studio/council). Both are armed the same way, on a single chat turn, from the composer. ## /docs/design/overview # Design overview The design surface in [Pathrule Studio](/docs/surfaces/desktop) is where a sentence becomes a real screen. You describe what you want, Studio builds it on a canvas, and you refine it by pointing at a layer and saying what should change. What comes out is a design document, not a picture: every layer has a stable identity, styles resolve through your tokens, and repeated structures stay components. That matters because the design is also an input. Your coding agent reads it to implement it, and reads it again to check its work, so the design has to state intent that survives translation into SwiftUI, Compose, or a React tree. ## Use the surface the work needs Design is a Studio surface for design-led work, not a prerequisite for using Pathrule. A coding-only team can stay in Chat, Tasks, source control and the terminal. When a task does start from a design, the handoff carries the same product context forward instead of asking the team to maintain another summary. ## What a design is made of - **Documents and screens.** One document holds the screens that belong together. Each screen has an authored canvas size and sits on a shared plane. - **Layers with stable ids.** A layer keeps its identity across edits, which is what lets an agent fix "the layer the finding named" instead of guessing at coordinates. - **Tokens, not literals.** Colour, spacing, and type resolve through token variables so a change at the source moves every screen that uses it. - **Components and instances.** A repeated structure is a component with properties and variants, and each use is an instance that can swap content without drifting from the original. - **A medium.** A design is authored for web, iOS, Android, a social format, or an editorial page. The medium decides the grid, the safe zones, and which primitives are appropriate. ## Design intent, not appearance-specific markup An agent reads structured intent rather than appearance-specific markup. That keeps implementation grounded in layout relationships and the target platform, whether the output is SwiftUI, Compose or a React tree. The design is read in focused slices: - **The index** lists every document and screen with node, instance, and token counts, plus the flow node for a screen that belongs to a journey. - **A screen** returns box, layout direction, sizing, resolved appearance, token variables, component instances, and text, per node. - **A node** drills into one subtree when a screen is too large to hold at once. The single most important field in that payload is **sizing**. `fill` means a node takes the space its container gives it, `hug` means it wraps its content, and both are relationships that survive a device nobody drew. `fixed` is a number that only holds at the width the design was authored at. An implementation that turns `fill` into a pinned width because the design happened to be drawn at 402px looks correct in review and breaks on the next phone. ## Readiness: what the design does not say Every document reports whether a design system is attached, and every screen reports how much of itself is actually bound: how many distinct colour values are literal rather than token-bound, how many repeated structures were drawn by hand instead of as components, and whether the screen sits in a flow. This exists so that an implementation can be honest. With no bindings available, the right move is to implement from the project's own tokens and list every unbound value in the run summary. Inventing a binding, or silently baking a literal, is what turns a design system into decoration. ## Working on several screens at once A document can run up to three design pages concurrently, each with its own AI turn, its own pending question, and its own recovery. A failure on one page does not reload another, and a style you paste is scoped to the page you pasted it into. ## What to read next - [Bringing a design in from Figma](/docs/design/figma) for the transfer path and what survives it. - [Flows and prototypes](/docs/design/flows) for wiring screens together and playing the result. - [Verifying a design against the running app](/docs/design/verify) for the finish condition. - [Sharing a design](/docs/design/sharing) for the encrypted public link. ## /docs/design/figma # Bringing a design in from Figma A **design link** binds a Figma file to a workspace. Once linked, frames you transfer keep a connection to their source, so Pathrule can tell you when the Figma file has moved on and the code bound to it has not. ## Setting up a link 1. In the Design surface, add a design link and choose the Figma file. 2. Supply your Figma access token when prompted. It is used for that one registration request, and it is never persisted or logged. The request also verifies your Pathrule session and your workspace access before anything is written. 3. Pathrule registers a webhook on the file so later changes arrive as drift notices instead of being discovered by accident weeks later. You can unregister a link at any time, which removes the webhook and stops the notices. ## What a transfer gives you A transfer produces a **pixel-exact contract**, not shippable code. The frames arrive as a Pathrule design: layers with stable ids, geometry, sizing, layout direction, token variables, component instances, and text. Images are recoded to WebP on the way in, so a transferred screen does not drag a multi-megabyte PNG through every later read. The transfer target is a design contract. Framework implementation remains project-native and should be written from the design's intent using your project's own primitives. ## Implementing a transferred design Follow this order. It is not stylistic. 1. **Tokens first.** A screen implemented before the token it depends on gets literal values baked in, and nobody goes back to unpick them. 2. **Components next**, because every screen inherits them. 3. **Screens last**, and only where the design actually changed. Two rules go with it: - **Bind the token variable, never the resolved value.** A hardcoded hex is the exact failure this pipeline exists to prevent. - **Never invent a name, a role, or a behaviour the design does not state.** Report the gap in your run summary instead. A design that says nothing about an empty state is a question, not a licence. ## When Figma and the render disagree If a frame came from Figma, a [fidelity check](/docs/design/verify) treats the Figma metadata as the reference in preference to Pathrule's own render. Comparing an implementation against a Pathrule render of a Figma frame would certify an importer bug as correct, so the check goes back to the source of truth. Colour is the exception in the other direction: Figma metadata carries no colour, so appearance findings always come from the design's resolved paint. ## What to read next - [Design overview](/docs/design/overview) for how a design is read as intent. - [Verifying a design against the running app](/docs/design/verify) for the finish condition on a transferred screen. ## /docs/design/flows # Flows and prototypes A screen on its own says what something looks like. A flow says what happens next, and that is the half an implementation usually has to guess. ## Connecting screens Pick the connect tool, drag from a control to a destination screen, and an interaction popover asks for the three things a transition needs: - **The action**: navigate, open an overlay, go back, or dismiss. - **The gesture**: what the user does to trigger it. - **The motion**: how the transition moves, including a timeout transition for a screen that advances on its own. Connections are drawn on their own arrow layer above the canvas, so the graph stays readable without changing the screens under it. ## Playing it Preview runs the graph inside a device shell at the device you chose, and it plays what you would actually be able to do: - Forward navigation and **walk back** through the history you built. - **Overlays** on their own stack, so dismissing a sheet returns you to the screen underneath rather than to the previous route. - **Hover** states where the medium has them. - **Timeout transitions** for screens that advance without input. ## What a flow tells an agent A screen that belongs to a journey reports its flow node: whether it is an entry point, where it sits in the traversal order, its route, and its outgoing transitions. A control that leaves the screen reports the destination's flow id and the event that fires it, and an input that carries state forward reports the field it fills. The rule that follows is short: **implement navigation from the flow, never from a button's label.** "Continue" is not a destination, and two screens in the same product can both have one. A screen that reports it is not in a flow is stating a gap. The right response is to say so, not to invent a destination. ## Running the flow as a test The same graph can be executed against the running app. Each transition becomes a step: perform the gesture on the control, expect to arrive at the destination screen. It is the cheapest way to catch the case where every screen is pixel-correct and the wiring between two of them is wrong. See [verifying a design against the running app](/docs/design/verify) for how the app is brought up and observed. ## Sharing a prototype A [shared design](/docs/design/sharing) carries the flow graph with it, so whoever opens the link plays the prototype instead of paging through static frames. The viewer walks the graph you published; it has no connect tool and no write path back. ## What to read next - [Verifying a design against the running app](/docs/design/verify). - [Sharing a design](/docs/design/sharing). ## /docs/design/verify # Verifying a design against the running app Reading the code and deciding it looks right is not verification. A fidelity check renders the real thing, reads it back, and compares it to the design node by node. This is the finish condition for design work: a design transfer proves the design moved, not that the code followed. Fidelity is one gate in a wider contract. Readiness reports what the design specifies. Component and token checks validate bindings. Runtime fidelity then checks structure, paint and geometry, while flows verify the journey. A pass in one gate never hides a finding in another. ## How a check runs 1. **The app comes up.** A dev server for web, a simulator run for iOS or Android. The agent starts it rather than asking you to. 2. **The result is observed.** On web, the rendered nodes. On native, the accessibility tree of the running app. 3. **It is compared to a reference.** In order of authority: Figma metadata when the screen came from Figma, otherwise the design's own geometry. 4. **Findings come back named.** Each one identifies the layer and the axis, for example "StatusBadge > Dot is 8px low", so one fix per iteration is real progress. ## Reading the findings - **Blocking findings must reach zero**, at every width the design was authored at. - **Text-metric findings are advisory.** Figma and a rendering engine never agree to the pixel on glyph advance, and blocking on that hides real layout drift behind noise. - **Low-confidence findings are advisory** too: they sit on a node pair that was guessed rather than matched by identity. Fix the layer the finding names. Nudging nearby values until the numbers agree produces a screen that passes the check and drifts everywhere else. ## Make the matching exact Matching is exact when the code carries the design's node id, and heuristic otherwise: - **Web:** emit the design node id as a `data-pr-*` attribute. - **Native:** set it as the `accessibilityIdentifier`. Heuristic matching still works, but it produces findings on node pairs that were guessed, and a guessed pair is where a confident wrong report comes from. If you want findings you can act on, emit the id. ## Check the reference before trusting a clean report A pass is only as wide as what it compared against. When the design is open in Studio, the reference is the whole node tree. When it is not, the reference falls back to the flow-control hotspots, which is a handful of controls rather than the screen. A clean report against the narrow reference is not the same result, so read which reference was used before calling the screen done. ## Scope - Touch only the files the task lists. If the correct fix needs another file, say so in the run summary instead of widening silently. - A design drift fix runs on its own branch, never straight onto the default branch. - Only a verified run may mark a code binding as synced. ## What to read next - [Flows and prototypes](/docs/design/flows) for running the journey, not just the screen. - [Bringing a design in from Figma](/docs/design/figma) for what the reference is on a transferred frame. ## /docs/design/sharing # Sharing a design A design is worth more in front of someone else. Studio publishes one as a read-only link that opens in any browser, with no Pathrule account on the other end. ## What gets published, and what we can see The share payload is **encrypted on your machine** before upload, and the key travels in the link's `#` fragment. Browsers never send a fragment to a server, so the viewer decrypts client-side and Pathrule holds ciphertext it cannot read. That is the whole point of the design: a public link should not mean a readable copy on someone else's disk. Two consequences worth stating plainly: - **Anyone who has the link can open it.** Encryption protects the content from us and from anyone without the link, not from someone the link was forwarded to. Add a **password** to the link when the audience should be narrower. - **Revoking works forward, not backward.** Revoking stops the viewer serving the design. It cannot retract a copy already opened by someone who had the link. ## It plays, it does not just render The share carries the [flow graph](/docs/design/flows), so the viewer runs the prototype: transitions, walk back, overlays, hover states, and timeouts, inside the device the design was published for. If no device was chosen, each screen plays at its authored canvas size. The viewer is strictly read-only. There is no connect tool and no write path back into your workspace. ## Comments A shared link can carry pinned comments. Someone with the link drops a pin on the spot they mean, and the comment appears live on your side, attached to a place instead of a paragraph of description. Comments can be turned off for a link at any time. ## The team library On a Team plan, designs your teammates author appear in a members-only library inside your organization. You can watch them update live and comment on them without anyone publishing a public link at all. Use the team library for work in progress, and a share link for the people outside it. ## What to read next - [Flows and prototypes](/docs/design/flows) for what the viewer is playing. - [Real-time collaboration](/docs/teams/real-time-collaboration) for how team surfaces stay in sync. ## /docs/design/design-system # UI kits, components and variables A design in Studio is not a drawing of components, it is built from them. UI kits, components, variables and styles are first-class objects on the canvas, and they are the same objects the code handoff reads. ## UI kits A kit is a starting library for a platform: the components, type and colour a native iOS screen or a web page already expects. You attach a kit to a design and its components become insertable, so the first screen is assembled rather than drawn. Kits are per platform, because an iOS tab bar and a web navigation bar are not the same component with different padding. ## Components Components live in their own panel, and only libraries that actually hold components appear there: a variables-only library never shows up in a place you go to find something to insert. - **Create from selection** authors what you have drawn into the components library. - **Search** filters by name, and a grid or list control changes tile density. - **Multi-select** exists because an import can drop a hundred components into a library at once, and pruning that one context menu at a time is not a real cleanup path. Select mode turns tiles into checkboxes, "All" takes the current search result so a query narrows the batch, and the delete is confirmed once. ## Variants Sibling components that share a name prefix are combined into a variant set automatically. `Button/Primary`, `Button/Secondary` and `Button/Ghost` become one component with a property, without a manual "combine as variants" step. An instance then swaps between variants from the inspector, and a component property switch exposes booleans and enums the component author declared. ## Variables and modes Variables are values with a name, organised into collections and groups, and defined per **mode**. Light and dark are the obvious pair; brand, density or platform are the ones that make the feature earn its keep. The editor is a tree of collections on the left and a name plus per-mode table on the right, so changing a value in every mode is one row rather than a hunt through a design. A compact panel handles the common edit, and a full editor opens for the work that needs room, with nothing lost between the two. ## Design tokens The variables are the tokens. There is no separate export step that turns one into the other and then drifts. When a design hands off to code, the tokens travel with it. A code binding is accepted only when the library, token identity, variable name, mode and property scope agree. A fill token cannot silently become a text token, and an unresolved proposal stays visible for review instead of being mistaken for a successful match. When the evidence agrees, the handoff says "this is your `--surface-2`" rather than "this is `#16191E`". See [Design to code](/docs/design/code-handoff). ## /docs/design/motion # Motion Motion in Studio is a real timeline, and what it produces is plain CSS. ## The timeline The Design surface's bottom dock is a motion timeline in the shape you would expect from an animation tool: a time ruler, a playhead, a bar for every animated element, and, when a layer is selected, one track per animated property beneath it. Opacity, position, scale, rotation, blur, colour and background each keyframe **independently**. That is the model that makes real motion possible: a card that fades while it rises and settles is three curves, not one preset with a duration. Each track has its own keyframe diamonds, a previous, toggle, next control, an inline value editor, and a marker at the playhead when you are between two keys rather than on one. ## It plays live Play and scrub drive the actual preview rather than a rendered approximation, through the browser's own animation engine. What you are watching is the animation, at the frame you are scrubbed to. Motion edits are live edits: they never reload the canvas, because reloading would tear down the running animation in the middle of the change you are making. ## What comes out is CSS Every edit rewrites the motion source on the design and re-bakes it into a compiled block of **pure CSS**. No runtime, no animation library, no JavaScript on the page that renders it. That matters twice. A shared prototype animates for a viewer with nothing installed, and the handoff to code is the animation itself rather than a description of it: a developer receives keyframes they can paste, not a note saying "fades in, 300ms, ease out". ## /docs/design/code-handoff # Design to code Handing a design to an agent usually means pasting an image and hoping. Studio hands over a structured document instead, and the useful part of it is the parts that point back into your repository. ## What the agent receives - **The screen's semantics**, not its markup: what each element is, how it is laid out, and how it responds, extracted from the design's own representation rather than scraped from rendered HTML. - **The tokens it uses**, matched against the tokens that already exist in your project. Where a design variable corresponds to a code token, the handoff says so, so the agent writes your token name rather than a hex value that will be wrong the first time someone changes the theme. - **Component bindings.** Where a design component corresponds to a component in your codebase, the binding carries the source path, supported platform and compatible prop map. An agent that has a proved binding to `packages/ui/Button.tsx` writes an instance. Without that evidence, the handoff keeps the component explicitly unbound instead of inventing a source component. - **The node ids**, carried into the code. This is small and it pays twice: it makes a later fidelity comparison exact, and it makes an automated tap on that element unambiguous when the flow becomes a test. - **The motion**, as the compiled CSS described in [Motion](/docs/design/motion). - **The assets** the screen actually uses. ## How a component match is accepted Project discovery is bounded and read-only. It inventories exported contracts without executing the application, supports React, Vue, Svelte, SwiftUI and Compose, and respects configured include, exclude and import-path boundaries. A component becomes an automatic binding only when all of these checks agree: - Its name has one supported match after conservative normalization. - The candidate belongs to the requested platform. - Prop names and types are compatible. - Enum and variant options agree. - No second candidate is close enough to make the result ambiguous. The output carries the evidence state: `matched`, `ambiguous` or `unmapped`, plus a reason. A confidence value never overrides an incompatible prop contract or a platform boundary. ## Where unmatched components go A binding that matched is a fact. A binding that did not is also information, and it is reported rather than dropped. It becomes a review list: configure a project boundary, choose among ambiguous candidates, or create the component when it is genuinely missing. That turns a handoff into a work list instead of an argument about whether the implementation is faithful. ## The other direction The same map works backwards. Studio can read the components and tokens that exist in your project, which is what lets a design be authored against what is really there, and what lets a code connect draft be generated for the components whose contracts correspond. [How Pathrule proves hard claims](/docs/start/technical-proof) collects the binding, readiness and fidelity gates in one technical reference. ## /docs/design/ui-tests # Prototypes as UI tests A prototype already says press this, arrive there. That is a test case. The useful part is that nobody wrote it: it came out of the design, and when the design changes the test changes with it. ## How it works A flow in the Design surface is a graph: screens, and transitions with an event and an action. Pathrule compiles that graph into a sequence of simulator actions and runs it against your app in the [simulator](/docs/studio/simulator). Taps are resolved by accessibility identifier or by label, which is the second reason the design's node ids travel into the code at handoff: the same id that makes a fidelity comparison exact makes the tap unambiguous. ## One source for the flow and the generated test A test written by hand describes the flow as it was on the day someone wrote it. The design moves, the test does not, and after a few months the suite is a record of an old product. Here the flow and the test are the same object. Rewire a transition and the test takes the new route on its next run, because there is no second copy of the journey to keep in step. ## An authoring problem is not a test failure This is the rule that makes the report worth reading. A graph with a screen nothing reaches, or a transition whose trigger has no visible control, is a **design defect**. Reporting it as "step 3 failed" teaches you to distrust the whole run, and a report you distrust is a report you stop opening. So the flow is audited before it is executed, and those problems are reported as what they are: something to fix in the design, separate from what the app did when the flow was actually run. ## /docs/content/memories # Writing memories A memory is a short markdown note your team writes down so the assistant can read it later. Memories live at a workspace path, and they only surface when the assistant is working under that path. They are the most common content type in Pathrule and the easiest to start with. This page covers when to write a memory, how to structure it, and how scope and versioning work. ## When to write a memory Reach for a memory when you have a piece of knowledge that is not obvious from the code and is likely to come up again. - **Decisions.** "We use Postgres on Supabase for everything in this repo. Do not bring in an ORM. Use the supabase-js client directly." - **Gotchas.** "If you change the `orders.status` enum you must run the data migration before the schema migration. The order is reversed from the rest of the schema." - **Postmortems.** "On 2026-04-12 we shipped a webhook handler that double charged customers because we did not check the Stripe idempotency key. Always pass it now." - **Conventions.** "Tests live next to the file they test, not under a parallel `__tests__` directory." - **Tribal knowledge.** "Only one person remembers why this flag exists. It is still required because of a runtime quirk in upstream." Skip memories for things the code already says clearly, things that change weekly, or things that are entirely personal preference. ## Structure Every memory has a title and a markdown body. Keep both small. - **Title:** short, declarative, fits in a sidebar. "Postgres only. No ORM." beats "Notes on database access patterns". - **Body:** the smallest amount of markdown that makes the point. Bullets are usually clearer than paragraphs. Include one example if it helps. There is no required template, but a useful default is: ```markdown The constraint or fact in one sentence. Why: - The reason this matters or the incident that prompted it. How to apply: - The concrete thing the assistant should do when the topic comes up. ``` ## Path scope The path is half the memory. It decides where the memory surfaces. - A memory at `/apps/api/payments` surfaces for any work under `apps/api/payments`. - A memory at `/apps/api` surfaces for the whole api directory. - A memory at `/` surfaces everywhere in the workspace. Pick the most specific path that still covers the cases you want. A workspace level memory about payments noise is worse than a payments folder memory about payments. ## Versioning and concurrent edits Every save returns a version token. The next save must carry that token, otherwise it conflicts. This protects your team from two people overwriting each other. - When the UI sees a conflict, it shows three options: keep mine, take theirs, or run a three way merge. - When the assistant tries to update via MCP, it gets a clear error and can either retry with the latest version or hand the conflict back to the user. Conflicts are rare in practice because memories are usually small and focused, but the safety net is always on. ## Who writes them - **Humans** writing in Pathrule Studio. - **The assistant** writing through the `pathrule_write_memory` MCP tool when the user asks it to save something. The runtime tags the source as `claude` (or the relevant client) so you can see which memories were AI authored. Both sources land in the same place. The assistant reads what the human wrote, and the human reads what the assistant wrote. ## How memory quality stays reviewable Pathrule keeps a memory narrow and inspectable through several independent controls: - General documentation is offered during setup rather than imported automatically. Live instruction files, their import chain, tool rules and decision records have stronger evidence that they are active knowledge. - An agent proposes lasting knowledge and writes it only after approval. - Path scope limits where the entry can surface, and an entry outside the current path still has to clear the relevance floor. - Measured usage may reorder qualifying entries, but it cannot lift an unrelated memory past that floor. - Self-audit raises stale, conflicting, unused or path-invalid entries for review. Edits are versioned and deletion is reversible. The resulting operating model is a small set of narrow, reviewable decisions and gotchas, not a large archive copied into the workspace. See [How Pathrule proves hard claims](/docs/start/technical-proof) for the full technical contract. ## Reading versus citing The most relevant memories arrive as full bodies the assistant can act on directly. Less certain candidates arrive as titles with ids; the assistant reads one in full with `pathrule_read_memory` before relying on it. This keeps uncertain material out of the default payload without turning strong matches into extra round trips. When you read memories in the UI, you see both the title list and the bodies. The same index drives both surfaces. ## Anti patterns - **One huge "all my notes" memory.** Split by topic and scope. Smaller and path scoped beats long and global every time. - **Memories that say what the code already says.** The assistant can read the code. Reserve memories for the why and the gotcha. - **Stale memories.** Update or delete them when the underlying decision changes. Pathrule's self-audit will flag obvious stale items, but a human eye is faster. ## What to read next - [Writing rules](/docs/content/rules) for constraints with priority. - [Writing skills](/docs/content/skills) for reusable procedures. - [Core concepts](/docs/start/core-concepts) for the workspace tree these attach to. ## /docs/content/rules # Writing rules A rule is a constraint the assistant must follow inside a scope. Rules are the strongest piece of content in Pathrule: a well placed strict rule blocks a class of mistake before it can land. This page covers when to write a rule, how to choose scope, priority and enforcement, and the patterns to avoid. ## When to write a rule Reach for a rule when there is a thing the assistant must not do, or a thing it must always do, in a specific part of the codebase. - "Never use the service role key in browser code." - "All money values are stored as integers in cents. Never use floats." - "Migrations must run before the matching code change. No exceptions." - "JSX files in `apps/web` use Tailwind classes only. No CSS modules, no inline styles." If the answer is "it depends on the situation, the assistant should think about it," that is a memory, not a rule. Rules are for non negotiable things. ## Scope types Every rule has a scope type that decides which paths or files it applies to. - **`folder`.** Applies to a directory subtree. Best for area specific rules: anything that lives under `apps/api/auth`, anything under `services/billing`. - **`file_type`.** Applies to files matching a glob like `*.tsx` or `**/*.test.ts`. Best for cross cutting concerns that are tied to a file kind, not a directory. - **`project`.** Applies everywhere in the workspace. Use sparingly. A project rule rides every prompt. The scope and the node path the rule is attached to together decide what the assistant sees. A `folder` rule attached at `/apps/web` covers anything under `apps/web`. ## Priority levels Priority decides how aggressively the rule shows up. - **`high`.** Always injected when scope matches. Use for things that cause bugs, security regressions, or compliance issues if violated. - **`medium`.** The default. Surfaces when the hook believes the rule is relevant for the current task. Use for "almost always but not load bearing". - **`low`.** Stylistic. Surfaces when there is room and the topic is on point. Use for taste and convention. High priority is a budget. If half your rules are high priority, none of them are. Pick the ones that really cannot be violated. ## Enforcement: advisory and strict Enforcement is a separate setting from priority. Priority ranks how strongly a rule surfaces; enforcement decides what happens on a violation. - **`advisory`.** The rule is context. The assistant weighs it and decides how to apply it. Most rules are advisory. - **`strict`.** A strict rule with a matching pattern is enforced by the local hook, which blocks a violating change before it lands and surfaces the rule as the reason. Reach for strict only when a violation must not be allowed through. Studio handles strict enforcement for the agents it runs. Pathrule CLI also registers the available hooks for standalone Claude Code, Cursor, Codex and GitHub Copilot. Windsurf and the Remote MCP surface receive rules as context but have no Pathrule pre-write blocking event. ## Structure A rule has a name and a body. Keep the body imperative and short. ```markdown Name: No service role key in browser code Body: - Never import SUPABASE_SERVICE_ROLE_KEY in any file under apps/web. - Use the anon key plus row level security. - If you need server only access, do it from apps/api or a server action. ``` The shape that works best in practice is one constraint per rule with a small bulleted body. Long prose rules get skimmed by both humans and assistants. ## Reusable, not duplicated A rule is a workspace level object. It can be attached to multiple nodes through a small join. If you have the same constraint that applies to two distant folders, attach the same rule object to both rather than copy pasting the text. This is mostly invisible at write time but matters when you need to update the rule: one edit, and every attachment sees it. ## Versioning and concurrent edits Rules carry a version token like memories. Two teammates editing the same rule at the same time will conflict cleanly rather than overwrite each other. The conflict resolution UI gives the same three options: keep mine, take theirs, or three way merge. ## How rules show up to the assistant - **High priority rules** are injected into the assistant's context for every matching scope. They appear in the Pathrule section of the context surface. - **Medium and low priority rules** go through relevance filtering. They are still listed in the rule index the assistant can read, but only the relevant ones ride along on a given turn. Whether a rule can block a change, rather than just inform the assistant, is set by its enforcement mode (advisory or strict), not by its priority. ## Anti patterns - **High priority for everything.** Pick the rules that really matter. The rest should be medium. - **Rules that read like memories.** "We tend to prefer X" is a memory. "Never do Y" is a rule. - **Rules that overlap.** Two high priority rules with conflicting language is worse than one clear rule. - **Project scope used by default.** Most rules belong under a folder. Pull a rule up to `project` only if it really applies everywhere. ## What to read next - [Writing memories](/docs/content/memories) for facts and decisions that are not constraints. - [Writing skills](/docs/content/skills) for reusable procedures the assistant can invoke. - [How hooks work](/docs/hooks/how-hooks-work) for how the runtime decides which rules to surface. ## /docs/content/skills # Writing skills A skill is a named procedure the assistant can invoke instead of re deriving the steps every time. Memories tell the assistant what is true. Rules tell it what not to do. Skills tell it how to do a specific job, step by step. This page covers when to write a skill, what goes inside one, and how skills are stored and attached. ## When to write a skill Reach for a skill when you notice the same pattern repeating. The signal is "the assistant keeps walking through the same set of steps and sometimes misses one". - **Operational procedures.** "Replay a Stripe webhook locally." "Regenerate the seed fixtures." "Run the pre release checklist." - **Custom workflows.** "Open a draft PR with the right labels and the right reviewers." "Bump the version, tag, and push." - **Domain specific guidance.** "Build a new analytics event end to end: column, type, dashboard." If the pattern is one or two lines, a memory is enough. Reach for a skill when the procedure has more than three steps or carries any "do this in this order" requirement. ## Sources A skill record carries a source value that tells Pathrule where its body lives. - **`manual`.** The body is authored directly in Pathrule and stored as is. The default. Use this when you want the procedure to be fully owned by the workspace. - **`template`.** A Pathrule provided starter skill, copied into the workspace and editable from there. - **`github_ref`.** The skill points at an external GitHub URL. The runtime fetches and caches the body. Use this for skills published by skill ecosystems you trust. For `github_ref` skills, the cached body is the snapshot Pathrule served last. If the upstream skill changes, the workspace picks it up on the next refresh. ## SKILL.md structure A skill is a small markdown file with frontmatter followed by the procedure body. ```markdown --- name: replay-stripe-webhook description: Replay a Stripe webhook against the local server with the right signing secret and the right idempotency key handling. --- # Replay a Stripe webhook Use this when a payment event from production needs to be reproduced locally. ## When to invoke - A customer reports a missing receipt and you have the event id. - You are debugging a webhook handler change. ## Procedure 1. Find the event in Stripe Dashboard. Copy its id. 2. Run `stripe events resend evt_xxx --webhook-endpoint we_local`. 3. Watch the local handler. It must accept and process the event without double charging. 4. If the handler returns 5xx, the customer support page is the next stop, not a retry. ## What NOT to do - Do not replay against production webhooks. - Do not skip the idempotency key check. ``` Frontmatter must include `name` and `description`. Everything below is the body the assistant follows. The body can be as short or as long as it needs to be. ## Attachment A skill is a workspace level object. It is attached to nodes through a small join, the same way rules are. One skill can be attached to many paths. In practice you attach a skill to the node where the procedure is most relevant. The replay webhook skill goes on `services/billing/webhooks`. The release skill goes at the workspace root. The assistant discovers skills through the hook supervisor (same way it discovers memories and rules) or via the `pathrule_list_memories` and related MCP tools. ## Invoke a skill on demand with `::skill-name` Usually the assistant picks the right skill on its own. When you want to force a specific one, type `::` followed by the skill name anywhere in your prompt, for example `::release-check` or `::replay-stripe-webhook`. For that turn the assistant treats the named skill as a mandatory workflow to follow, with no long instructions to write. It is designed to fail safe: - If the name matches no skill, or matches more than one, Pathrule does nothing rather than guess. - It ignores code-like uses of `::` such as `button::before` or `std::vector`, so ordinary prompts are never misread. That makes `::skill-name` a quick, path-independent way to pull a known team procedure into the current turn. ## Authoring flow Two flows land in the same place. - **Manual authoring.** Open Pathrule Studio, create a new skill at the right node, paste the SKILL.md body, save. - **Assistant authoring.** In Claude Code (or any MCP client) the user asks the assistant to "make this into a skill". The assistant uses a small skill creator pattern: capture intent, interview the user, draft the SKILL.md, then call `pathrule_write_skill` with the full body. For low commitment scenarios the assistant drafts the skill in the conversation and waits for approval before calling `pathrule_write_skill`. The persisted record is therefore the reviewed draft, not a silent background write. ## Versioning and concurrent edits Skills carry a version token like memories and rules. Two teammates editing the same skill conflict cleanly. The same three way merge UI applies. ## Anti patterns - **Skills that are really memories.** If the body is "this is true about how we work", make it a memory. - **Skills that are really rules.** If the body is "never do X", make it a rule. - **One skill that does too much.** Split into two named skills if the procedure has two distinct entry points. - **Pulling external skills you do not trust.** A `github_ref` skill is code that runs in your assistant's instructions. Treat it like a dependency. ## What to read next - [Writing memories](/docs/content/memories) for facts and decisions. - [Writing rules](/docs/content/rules) for constraints. - [MCP tools reference](/docs/mcp/tools-reference) for the tools the assistant uses to write skills. ## /docs/content/suggestions # Suggestions and self-audit Team knowledge rots. Paths get renamed, milestones ship, dependency pins drift, a rule stops matching anything. Pathrule runs a background self-audit so that decay surfaces as a short list of suggestions instead of silently misleading the assistant. The important property: the self-audit only ever *suggests*. Pathrule never edits or deletes your memories, rules or skills on its own. ## What the self-audit checks A set of independent checks runs on its own schedule and flags entries worth a look: - Memories or rules that cite a path or file that no longer exists. - Nodes whose attached path is now empty. - Rules that have not matched anything in a long time, unless delivery itself has gone quiet. A silent feed is one platform fact, not a hundred pieces of advice about your knowledge. - Entries past a date or milestone they referenced. - Neighbouring entries that now say contradicting things. Each finding lands in the Suggestions tab, names the affected node, and explains the signal that fired. Nothing about your source code is involved; the checks read your stored memories and rules plus the workspace structure. The set of checks is curated on its own evidence. Every check is measured against how often its findings are acted on, and one that keeps producing findings nobody accepts is retired rather than left to fill the tab. A suggestion you would always ignore is not a smaller problem than a missing one; it is the reason people stop reading the tab at all. ## Freshness driven by Git The strongest staleness signal is the commit that just landed. Pathrule watches your repository's `HEAD` reference, which is a few bytes, and when it moves it maps the **paths** that changed back to the memories that reference them. Three properties make this safe to leave on: - **It is content-free.** Only changed paths are compared against the paths your knowledge cites. Repository snippets never reach the database, and no diff is uploaded. - **It needs no Git hooks.** Nothing is installed into your repository. A merge or a commit is noticed by polling that one tiny reference, so there is no hook to break someone else's workflow. - **It invokes no model.** The mapping is deterministic. A large scan checkpoints and resumes rather than restarting, per branch. What comes out is an ordinary suggestion: "this memory describes a path that changed in the last commit". You still decide whether it needs a fix. ## Reviewing suggestions A suggestion is a prompt for a human decision, not an action. For each one you can: - **Accept** and let your assistant apply the fix (see below). - **Edit** the entry yourself. - **Snooze** it for later. - **Archive** or **dismiss** it if it is not worth acting on. Suggestions your team keeps dismissing fade into the background over time, so the list stays worth reading. ## Suggestions close themselves when they stop being true You do not have to work through the list to keep it clean. A suggestion is a finding about the state of your knowledge at a moment in time, and most findings stop being true on their own. Each check re-runs on its own schedule. When a check runs again over the same workspace and no longer produces a finding, that finding is closed automatically. The memory it flagged was updated, the path it pointed at came back, the date it read as expired turned out to be current: whatever the reason, the check is the thing that decides, not a timer. This is why the list stays short without becoming forgetful. A finding that is **still** true is re-emitted on every run, so it stays open no matter how old it is. Something flagged three months ago and still unresolved is still on the list, because the check keeps confirming it. Something momentary, like a memory that looked stale for one afternoon while a branch was in flight, disappears without anyone touching it. Closed-by-recheck is recorded as exactly that, so it is never confused with a decision you made. Your accepts, edits and dismissals stay attributed to you. ## Repair through your assistant Pathrule does not patch your knowledge automatically. When you choose **Fix with AI**, the suggestion is queued as a refresh task for your next AI session. Your assistant then: 1. Picks up the refresh task through the MCP tools. 2. Inspects the current code and the flagged entry with its own file-access tools. 3. Drafts the update and writes it back through the Pathrule write tools. 4. Marks the task applied or rejected. You stay in control at both ends: the fix runs through your own assistant, and you review the change. See the [MCP tools reference](/docs/mcp/tools-reference) for the refresh tools the assistant uses. ## Nothing is one-way A repair is a normal versioned edit. Every change keeps its history, and a delete is a soft delete that stays restorable for thirty days and lands back at the same path on restore. If a suggested fix turns out to be wrong, you can roll it back. ## /docs/content/work-episodes # How did we solve this before Every time an AI session finishes a piece of work, it can log what happened: the area it touched, the action it took, the files involved, and a short summary ([what a session records](/docs/content/activity-log) covers that entry in full). On its own, each log is a single line in a long list. Work episodes turn that list into something a future session can actually use. Pathrule rolls related activity from a working session into a work episode: a titled record of one thing your team solved, with the subjects it was about, the paths and files it touched, the AI clients involved, and when it happened. Months later, when someone hits the same area again, that episode is there to recall. ## Recall is on demand, not on every prompt Work episodes do not ride along in every request. An ordinary prompt adds no history at all, so your context window is not paying a tax for memory you are not using. When your agent is doing the kind of work where the past matters (fixing a bug, debugging, refactoring, or exploring an unfamiliar area) Pathrule can include a few of the most relevant prior episodes in the context it returns. Your agent can also ask for prior work explicitly, and a strongly worded historical question ("how did we handle this last time") is enough to trigger a look. For small UI tweaks and brand-new features, episodes stay quiet, because anchoring fresh work to old patterns tends to cost more than it helps. ## What makes an episode relevant Relevance is computed from two plain signals and one preference, not from a guess: - What the work was about. An episode about authentication is a candidate when you are back in authentication, not when you are formatting a table. - Where the work happened. An episode that touched a path is a candidate when you are working at or under that path, in either direction. - How recent it was. Recent work is favored over stale work, because code drifts and old episodes describe a codebase that may no longer exist. The result is a short, ranked set: a handful of episodes at most, each compact enough to read at a glance. ## Skip beats wrong Pathrule would rather surface nothing than surface the wrong thing. If an episode has no real overlap with what you are doing, it is not shown. If the system is not confident, it stays quiet. If your workspace has not built up enough history yet to score reliably, recall short-circuits and returns nothing. You will not see a wall of vaguely related work; you will see the few episodes that earned their place, or none. ## Built from what you log, never from your code Work episodes are built only from the activity your agents log through Pathrule. Pathrule does not read, scan, or index your source files to build them. The same access control that governs the rest of your workspace governs episodes: they are scoped to your workspace, behind your team's per-user access, and identical for everyone who can see them. Episodes that keep getting used stick around. Episodes nobody returns to age out on their own, so the history stays a record of work that mattered rather than an ever-growing log. ## Where to find this Work episodes surface through the context your AI client receives, on the kinds of tasks where they help. You do not configure them per repo and you do not turn them on prompt by prompt. They are a property of a workspace that has accumulated real, logged work. See [Suggestions and self-audit](/docs/content/suggestions) for the related maintenance signals Pathrule raises about your stored memories and rules. ## /docs/content/activity-log # What an AI session records Most of what Pathrule learns about your project it learns from work, not from writing. When an AI session finishes a piece of work it records a short structured entry, and that single entry is what several other features are built on. This page is about what is in that entry, what is deliberately left out of it, and what it goes on to power. ## What is recorded Each entry is a handful of fields, all small: - **Area, action and scope.** What kind of thing was touched (`ui`, `backend`, `database`, `config`, `test`, `docs`), what was done to it (`create`, `update`, `fix`, `refactor`, `delete`, `style`), and at what level (a component, a page, an API, a migration, a service). - **Subjects.** Up to five lowercase keywords, the way you would tag the work in conversation. - **A one-sentence summary.** What changed and why, in a line. - **The paths it touched**, grouped by area. - **Which AI client** the session ran in, and when. - **How the turn went**: how many tool calls it took, how many failed, and a short code for each kind of failure (`timeout`, `exit_nonzero`, `not_found` and similar). Counts and codes only, never the command or the error text. That is the whole record. It is designed to be readable at a glance months later, which is also why it stays short. The assistant writes the sentence. Pathrule attaches the measurement. The summary, the area and the paths come from the session that did the work, while the tool-call count, the failures, and which of the delivered entries were actually consulted are observed by the layer that delivered them. That split matters: an assistant can forget to mention that four commands failed, and the count is there anyway. ## What is never recorded Your code is not in it. No file contents, no diffs, no patches, no commit messages, and no prompt text. The paths are there so later features can tell *where* work happened; the substance of the change is not stored. Paths are also **normalised before they are stored**. A path arrives as whatever the agent saw on that machine and is converted to workspace-relative form, so `/Users/you/projects/app/src/api.ts` becomes `src/api.ts`. Nothing machine-specific reaches shared team knowledge, and the same file is the same file whoever touched it. ## What one entry feeds The reason the record is worth keeping is what reads it: - **[Work episodes](/docs/content/work-episodes).** Related entries from one working session roll into a titled record of one thing your team solved, which a later session can recall. - **[Files that change together](/docs/retrieval/co-change).** The paths in each entry are what teaches Pathrule which files travel in pairs. - **Retrieval learning.** When knowledge was put in front of an agent and the agent then worked in that same area, that is evidence the knowledge was relevant. Over time it moves the ranking, described in [how retrieval works](/docs/retrieval/how-retrieval-works). - **[Staleness suggestions](/docs/content/suggestions).** Recent activity against a path is one of the signals that a memory referencing that path may have drifted. None of those needs a separate step from you. They all come from the same short entry. ## Logging never blocks the work One deliberate design choice is worth calling out, because it shows up in how the tool behaves. **Logging never fails for size.** If a summary runs long or a task touched dozens of files, the entry is trimmed on the server and stored, rather than rejected. Rejecting it would be worse than trimming it. An agent that gets a validation error reads it as "fix the arguments and try again", and spends the next several turns rewriting a summary instead of finishing your task. So the limits are applied quietly, on the way in, and the response tells the agent what was stored. ## What the failure counts are used for The tool-call and failure counts are how Pathrule answers "which files does this codebase make an assistant struggle in" from real work rather than from opinion. Two things read them. The first is a weekly grouping. Every failure is recorded as a triple: the kind of tool, the file it was working on, and a short code for how it failed. Grouped by week, that turns into a plain list of the files an assistant fails in most often, and what kind of failure it hits there. A file that shows up repeatedly under `file_not_found` is usually a stale path in your own docs or a moved module nothing updated. One under `syntax_error` is usually a file that is hard to edit safely. The second is retrieval learning. If a turn received knowledge from Pathrule and still ran into tool failures, the knowledge it was given takes a small negative signal, weighted by how bad the failure was. Permission, token-limit and rate-limit failures count more heavily than an ordinary miss. That signal joins the same learning loop described in [what makes knowledge rank higher](/docs/retrieval/how-retrieval-works), so knowledge that keeps showing up in turns that go badly gradually stops being chosen. ## What a failure count can and cannot see This depends on the assistant you use, and the honest answer is not uniform. File tools report properly. A failed read, edit or write arrives with its message, so it is classified and attributed to the right file. That is the case worth having, because a file path is what makes the number actionable. Shell exit status often does not. Some assistants do not report a non-zero exit code at all: a command that fails and one that succeeds arrive looking identical. Pathrule does not guess. It records what the assistant actually reported and classifies the rest as unknown rather than inventing a failure, because a wrong failure attached to a file is worse than a missing one. ## Access and scope Entries live in the workspace they were recorded in, behind the same per-user access control as memories, rules and skills. A teammate sees the activity for workspaces they can already see, and nothing else. Retention follows your plan, and the oldest entries age out on a schedule rather than accumulating forever. ## /docs/signals/overview # Signals overview For years the loop ran in one direction: a human explains a problem, the AI writes code, the product ships. If something then broke in production, it was on you to notice it, reconstruct the context, and explain it back to the assistant from scratch. Pathrule Signals adds the arrow that was always missing: **product to AI**. Your running product becomes something that can speak. When a real flow breaks or recovers, your agents hear about it directly, already carrying the paths, rules and memories that touch that part of the code. Signals is available today in Pathrule Studio. Signals is optional per workspace. Setup starts with a focused read-only scan, then shows a small proposal for a person to approve. Studio vendors a dependency-free SDK and adds only those approved points. Nothing starts observing a project from a generic background crawl. ## The idea in one line > Human → AI → Product is only half the loop. Signals lets the product answer back. ## What Signals is - **It watches, in the background.** Signals reads your product's real runtime events and coalesces repeats, so an idle product produces no noise. - **A deterministic reporter.** When an error or a flow crosses a worthiness threshold, Signals groups it into a single canonical incident and attaches a **Context Brief** built from facts Pathrule already holds, the resolved node path, the strict rules on it, the memories that explain it, and the recent activity around it. - **A runtime proof loop.** After a fix ships, Signals keeps watching the next release. It can tell you honestly whether the issue recurred, went quiet, or was actually verified in production. ## A narrow runtime-context contract - **Incident context, not user analytics.** Signals carries no funnels, sessions, per-user tracking or raw event warehouse. - **Deterministic evidence.** The Context Brief is built from stored facts before any person decides to act, with no LLM root-cause guess presented as fact. - **The existing execution path.** Signals stops at the handoff. After you approve a task, planning and code execution continue through the same Tasks and Chat flows. ## Why it matters The expensive part of fixing a production issue was never the fix, it was the discovery, the context rebuild, and the manual watch afterward. Signals removes all three. Your agent starts a task already knowing what happened, where it maps, why it matters, and which rules govern the code. And once the fix is out, you get told when production actually confirms it. ## What to read next - [How the loop works](/docs/signals/how-it-works) for detection, the Context Brief, the handoff, and the verification states. - [Setting up Signals](/docs/signals/setup) to turn it on in Pathrule Studio. - [Plans, quotas and retention](/docs/signals/plans-and-limits) for monthly limits and how long Signals are kept. ## /docs/signals/how-it-works # How the loop works Signals runs a five-step loop: **detect → explain → hand off → observe → report**. The first two steps are fully deterministic, no model call is needed to notice a problem or describe it. ## Before the loop: approved instrumentation Signals does not infer runtime behavior by scanning a production system from the outside. Studio first performs a bounded read-only repository scan and proposes one initialization point plus a small set of high-value error and event points. A person approves the set, and only then does Studio vendor the dependency-free SDK and add those points. Every point carries a structural flow and workspace node path, which is how a runtime event can resolve back to the knowledge and tasks that own that part of the product. ## 1. Detect Signals reads your product's real runtime events. Repeats of the same thing are coalesced into a single logical incident, identified by: ```text workspace + environment + kind + fingerprint ``` The release is treated as observation state, not identity, so the same error in a newer release stays **one** incident rather than spawning duplicates. An incident becomes card-worthy only when it crosses a policy threshold, for example, a production error that reaches a repeat count. ## 2. Explain: the Context Brief When an incident first becomes card-worthy, Signals attaches a compact **Context Brief** built from facts Pathrule already holds: ```text Pathrule Signals detected a production error. What happened - TypeError: checkout response was empty - First observed in release 1.8.0 - Seen 3 times in production Where - Resolved context: /apps/web/checkout - Flow: checkout Why this became a task - Production error reached the 3-occurrence threshold Relevant Pathrule context supplied - Rule: Refresh auth before retrying payment [strict] - Memory: Checkout recovery decision ``` Alongside it, Signals stores a versioned **Context Receipt**, the exact rules and memories, at the versions they were when the card was created. The receipt proves *which context was supplied*, not that the AI semantically followed every rule. The label is always **Context supplied**, never *Rules followed*. ## 3. Hand off Signals creates the same kind of Tasks card you already use, with the Context Brief in its prompt. That is where Signals stops. Everything after you start the card (investigation, code, tests, commit, review) is the existing Tasks flow, unchanged. One canonical incident creates **at most one** card. Later occurrences and releases can never create a second one. ## 4. Observe Once a newer production release appears, Signals starts watching it. Accepted production events act as coverage pulses; it does not keep a raw heartbeat history, only bounded aggregate coverage. ## 5. Report: the honest outcome Signals reports one of four states, and it never overstates the evidence: | State | Meaning | |---|---| | **Observing** | A different, newer release is connected and coverage is accumulating. | | **Recurred** | The same fingerprint appeared again in the candidate release. The incident reopens on the same card. | | **Quiet** | Healthy coverage passed the minimum window with no recurrence. Weaker than verified, it never marks a fix as done. | | **Verified** | The same flow succeeded enough times under healthy coverage, with no recurrence. The incident resolves and you get one notification. | Silence alone never counts as success. Only positive success evidence can verify a fix, and only within the same workspace, environment, flow, and candidate release. ## What happens to the linked card - **Verified** completes the linked Signals card (if it is not running) with a runtime-verified marker. - **Recurred** reopens that same card and never starts AI on its own, you approve it by starting it. - A **running** card is never interrupted or moved; its marker updates and the safe projection retries after the run settles. - **Quiet** and archived states never touch the card. ## What to read next - [Setting up Signals](/docs/signals/setup) to turn it on in Pathrule Studio. - [Plans, quotas and retention](/docs/signals/plans-and-limits) for limits and lifecycle. ## /docs/signals/setup # Setting up Signals Signals is part of Pathrule Studio and is enabled per workspace. Setup is proposal-first: Studio first discovers the few points that carry useful runtime context, then a person chooses what is allowed into the codebase. ## Turn it on 1. Open the workspace you want to monitor in Pathrule Studio. 2. Enable Signals for that workspace and start the `/signals` setup. 3. Studio asks your coding agent for a focused, read-only scan. The agent reads the project structure, entry points, existing error boundaries and important business milestones. It does not modify files, run the app or run tests during this pass. 4. Review the proposal. A typical project produces one initialization point and roughly 3 to 12 error or event points. Each proposal names its file, workspace node, structural flow, rationale and confidence. 5. Approve the points you want. Studio creates a workspace ingest connection, vendors its dependency-free single-file SDK and asks the coding agent to wire only the approved points under your normal permission policy. There is no package-registry install and no analytics account to configure. The code change is narrow and inspectable: one initialization call plus the points you approved. On Solo, one workspace can run Signals at a time; see [Plans, quotas and retention](/docs/signals/plans-and-limits) for the details. ## What can be proposed Signals has two runtime point types: - **Error:** a failure worth surfacing, such as an unhandled rejection, an error boundary or a failed critical operation. - **Event:** an important structural milestone, such as checkout completed, a job finished or feedback submitted. Each point may carry a structural flow such as `checkout` or `auth`, plus the workspace-relative node path that owns it. Setup does not propose users, sessions, funnels, request bodies, secrets, tokens or personal data. ## What the SDK guarantees The vendored SDK is designed to stay out of the host product's failure path. It bounds and coalesces queued work, redacts unsafe values, retries with backoff and swallows transport failure. Signals never throws a transport or quota failure into the application it observes. ## What you see Each incident shows up in the Signals view with: - **Status.** Active, observing a newer release, quiet, runtime verified, or recurred. - **What happened.** The message, environment, release, count, and when it was first and last seen. - **Why here.** The resolved node path and the flow it belongs to. - **Context supplied.** The exact rules and memories that were attached, with their versions. - **Runtime outcome.** The production evidence gathered after a fix, once observation has started. ## From incident to task When an incident crosses a worthiness threshold, Signals hands it to the same Tasks flow you already use, with a Context Brief in the card prompt. Everything after you start the card is unchanged. See [How the loop works](/docs/signals/how-it-works) for the full path from a production event to a verified fix. ## Availability Signals runs in Pathrule Studio. ## What to read next - [Signals overview](/docs/signals/overview) for the product story. - [How the loop works](/docs/signals/how-it-works) for detection, context, and verification. ## /docs/signals/plans-and-limits # Plans, quotas and retention Signals is a usage dimension alongside workspaces, memories and rules. The public unit is **Signals processed per month**, measured on a UTC calendar-month boundary (`00:00 UTC` on the first day) regardless of whether you bill monthly or yearly. ## Monthly limits | Plan | Signals / month | Monitored workspaces | |---|---:|---| | **Solo** | 1,500 | 1 | | **Team** | 100,000 | Unlimited, one shared quota | | **Business** | 500,000 | Unlimited, one shared quota | | **Enterprise** | Custom | Custom | - **Solo** is a real but deliberately bounded one-project experience: Signals runs in a single monitored workspace. Your other workspaces keep every non-Signals feature. - **Team** and **Business** share one organization-wide Signals quota across as many monitored workspaces as you like. Business has five times Team's capacity. - **Enterprise** uses a contract value; platform-wide abuse guards still apply. ## What counts - A valid error or event occurrence accepted for processing counts **once**. - A coalesced batch carries a delta; the accepted delta consumes the allowance even though it is one network request and one row update. - **Declarations, connection announcements, quota checks, rejected malformed payloads, and release-coverage touches do not count.** - Traffic suppressed beyond a per-fingerprint daily spike ceiling does not count. - A batch that crosses the monthly boundary is partially accepted up to the remaining allowance. There is no grace period past 100%. When the quota is exhausted, **Signals ingestion pauses for the rest of the period**, and nothing else does. Memories, rules, workspaces, and Tasks stay fully writable. The next period resumes automatically. ## Usage and warnings Your usage is shown like any other dimension: ```text Signals this period 842 / 1,500 Resets Aug 1 Monitored workspaces 1 / 1 ``` - At **80%**, a neutral usage warning. - At **90%**, a strong warning with an upgrade action. - At **100%**, new Signals are paused until reset; every other capability is unaffected. Studio also breaks down accepted, spike-suppressed, quota-suppressed, and cardinality-suppressed counts, so you can always see why something did not land. ## Guardrails Beyond the monthly quota, a few internal guards keep one runaway product from swamping your allowance or the platform: - **Spike ceiling.** A per-fingerprint daily cap stops a single runaway error from consuming the whole organization allowance; suppressed volume does not count. - **Hot-group cap.** A limit on concurrently active grouped identities stops a flood of unique fingerprints. Existing groups keep updating; new ones are suppressed and surfaced in Studio rather than failing silently. - **Rate limit.** A per-key request-rate ceiling, independent of monthly volume. ## Retention Signals keeps only what is useful and compacts the rest on a bounded schedule: | Data | Kept until | |---|---| | Unlinked production incident, unseen | 14 days, then deleted | | Unlinked development / preview incident, unseen | 7 days, then deleted | | Stale declaration, unseen | 30 days, then deleted | | Verified incident | Shown as proof for 30 days | | Verified / card-linked incident | Cold-compacted 90 days after last evidence | | Cold tombstone with no recurrence | Purged after 12 months | Cold compaction clears the heavy fields (message, stack, context receipt, detailed evidence) but keeps the small identity needed to prevent a duplicate task. A recurrence before the tombstone expires rehydrates the **same** incident and reuses the **same** card, it never creates a duplicate. ## What to read next - [Signals overview](/docs/signals/overview) for the product story. - [Setting up Signals](/docs/signals/setup) to turn it on in Pathrule Studio. ## /docs/signals/runtime-verification # Watching production A task that came from [Signals](/docs/signals/overview) does not end when it is merged. Merging is a claim, and the claim is checkable: the same runtime that reported the problem can say whether it stopped happening. So a Signals card carries a runtime state, and that state keeps moving after the work is done. ## The states - **Not verified yet.** The card exists, the fix has not shipped, or nothing has been observed since it did. - **Watching production.** The fix is out and Signals is watching the events that led to this card. This is the state a card sits in while the answer is still being earned. - **Quiet, not confirmed.** Nothing has come back, but not enough has happened to call it fixed either. A low-traffic path can be quiet because it is fixed or because nobody has hit it, and those are not the same sentence. - **Verified fixed.** Enough traffic has passed through the affected path without the issue returning. - **Issue returned.** It came back. The card reopens with the evidence attached rather than a new card appearing with no memory of the first attempt. - **Archived after healthy coverage.** The path has been healthy long enough that watching it further tells you nothing. ## Why "quiet" is its own state Most tools have two answers: fixed, or not fixed. That forces a guess whenever traffic is thin, and a guess in this position is always optimistic, because nothing arriving looks exactly like success. Separating "nothing came back" from "enough went through" is what keeps the verified state worth something. When a card says Verified fixed, it means traffic went through the path, not that the room went silent. ## Issue returned is the point The state that justifies the whole loop is the one nobody wants to see. A fix that regresses two weeks later normally comes back as a fresh report, disconnected from the work that was supposed to have solved it, and the team relearns the problem from scratch. Here the original card reopens. The attempt, the context it ran with, and the runtime evidence from both occurrences are in one place, so the second attempt starts from what the first one tried. ## Where you see it On the card, as a small state chip beside the Signals badge, with the time it last changed. Verified reads in the success tone, Issue returned in the alert tone, Watching production in the informational one, and the rest stay muted. It is a status, not a notification: the board does not interrupt you to say a card is still being watched. ## /docs/patterns/overview # Patterns overview A pattern is a ready-to-use package of team knowledge for a specific stack or job. Instead of starting a workspace empty and writing every memory, rule and skill by hand, you add a pattern and your AI assistant starts the project already knowing the conventions that stack tends to need. Each pattern is a bundle of the same three content types Pathrule already uses, and every piece arrives pre-scoped to the path it belongs to. A rule about server components lands on `/app`, a billing memory lands on the billing service, a review skill lands at the root. Nothing is dumped into one global file. ## Why patterns exist Most repositories share the same early questions. How should a Next.js App Router project split server and client components? Where do you keep Supabase row-level security rules? What is the safe way to handle a Stripe webhook? The answers are well understood, but every team rediscovers and re-types them. Patterns capture those answers once, as path-scoped Pathrule content, so a new workspace can adopt them in seconds: - **Pre-scoped, not pasted.** A pattern is not a prompt blob. Each piece declares the path it lives at, so your assistant only sees it where it is relevant. A UI tweak never has to read a database rule. - **Typed, not freeform.** A pattern is made of memories, rules and skills, the same types you write yourself. An imported rule keeps its scope, priority and enforcement mode; an imported skill is invocable by name. - **Yours after import.** Importing a pattern is a one-time seed, not a live subscription. The pieces become ordinary content in your workspace and you edit them like anything else. ## The catalog The public catalog lives at [pathrule.io/patterns](/patterns). Every package there is first-party and published under Apache-2.0, organised into categories: - **Framework** for app frameworks like Next.js App Router, Nuxt, SvelteKit, Astro and React Router. - **Frontend** for component, forms and styling conventions. - **Backend** for data access, APIs and server patterns. - **Billing** for payment and subscription flows. - **Infra** for build, deploy and platform concerns. - **Workflow** for review checklists and team process. Each catalog entry has its own page showing the full bundle grouped by path, a derived contents summary (how many rules, memories and skills it carries and how many paths it touches), the reference token used to import it, and a manual copy that works today. Every pattern is also served as plain markdown at `/patterns//raw`, so an AI assistant can read the whole bundle directly from a shared link. ## How a pattern fits the rest of Pathrule A pattern does not introduce a new runtime concept. It is a packaging format over the model you already know: - The pieces are [memories, rules and skills](/docs/start/core-concepts). - Each piece's path uses the same [path scope](/docs/start/core-concepts#path-scope) rule as content you write yourself. - Once imported, the pieces surface through the same [hooks](/docs/hooks/how-hooks-work) and the same just-in-time retrieval as the rest of your workspace. That is the whole idea: a pattern is a curated head start, expressed in the exact shape your assistant already reads. ## What to read next - [Anatomy of a pattern](/docs/patterns/anatomy) breaks down the content model: pieces, paths, versioning and the open package behind the catalog. - [Importing a pattern](/docs/patterns/importing) covers the one-token import, the path preview, and removing a bundle later. - [Core concepts](/docs/start/core-concepts) explains memories, rules and skills if you are new to the model. ## /docs/patterns/anatomy # Anatomy of a pattern A pattern is deliberately simple. It is a small bundle of typed pieces plus the metadata needed to display it, version it and match it to a project. Understanding the shape makes it obvious what you are getting when you import one. ## A pattern is a bundle of pieces Every pattern carries a list of pieces. Each piece is exactly one memory, one rule or one skill, and it knows where it should land. A piece declares: - **`kind`**: `memory`, `rule` or `skill`. This decides which content type it becomes on import. - **`nodePath`**: the workspace-relative path it belongs to, for example `/app`, `/services/billing`, or `/` for the root. This is the scope the piece is delivered with. - **`title`**: the memory title, rule name or skill name. - **`summary`**: a one-line description shown in the bundle list, separate from the body. - **`body`**: the full markdown content. This is exactly what gets written into your workspace, with no transformation. Because each piece names its own path, a pattern is path-scoped by construction. The bundle is not a single document that has to be filed somewhere; it is a set of pieces that already know where they go. ## Type-specific metadata Some pieces carry extra fields that match their content type, and these survive import intact. - **Rule pieces** can set a **scope type** (`folder`, `file_type` or `project`), a **priority** (`high`, `medium`, `low`) and an **enforcement mode** (`advisory` or `strict`). An imported rule keeps all three, so a strict, high-priority rule from a pattern behaves like one you wrote yourself, including being enforced at the hook. - **Skill pieces** carry a skill name and optional tags. After import the skill is discoverable and invocable by name, the same as any other workspace skill. - **Memory pieces** need no extra metadata; the body and path are enough. For the underlying meaning of scope, priority and enforcement, see [Core concepts](/docs/start/core-concepts#priority-and-enforcement). ## Counts and paths are derived A pattern never hand-maintains its own summary. The "12 rules, 7 memories, 4 skills" line and the list of target paths on each catalog page are computed from the pieces. That means the displayed contents can never drift from what the bundle actually contains. Add a rule to a pattern and its count updates on its own. ## Versioning and freshness Each pattern is versioned and dated so you can tell what you are adopting and when it last changed: - **`version`** is a display version like `v1`, also used in the import token. - **`updatedAt`** is the date of the last content change. It drives the freshness signal on the catalog and the last-modified date in the sitemap. - **`changelog`** is an optional list of human-readable entries, newest first, recording what changed between versions. Versioning matters because import is a one-time seed (see [Importing a pattern](/docs/patterns/importing)). When a pattern publishes a newer version, that surfaces as an explicit "new version available" prompt rather than a silent overwrite of content you may have already edited. ## Matching metadata A pattern can optionally declare what kind of project it fits, under an `appliesTo` block: relevant paths, stack tags (for example `nextjs`, `react`) and dependency names. The web catalog uses this for display and search. The same metadata is what lets the import flow check whether a pattern's stack matches your project before writing anything, and ask you to confirm when it does not. ## The open package The catalog is backed by a single open package, `@pathrule/patterns`, published under Apache-2.0. The package is pure and serializable: it carries the pattern definitions, their types and a few helper functions, with no dependency on any UI or cloud code. That keeps it readable as plain data and lets every surface consume the exact same bundles. Adding a pattern is one new entry registered in that package. Because the package is the single source of truth, the website, the import tooling and the markdown views all render the same content. ## What to read next - [Importing a pattern](/docs/patterns/importing) shows how a bundle gets written into your workspace and how to remove it. - [Patterns overview](/docs/patterns/overview) is the higher-level picture if you skipped it. - [Writing rules](/docs/content/rules) and [Writing skills](/docs/content/skills) cover the piece types in depth. ## /docs/patterns/importing # Importing a pattern You can adopt any pattern in two ways. You can copy the bundle by hand from the catalog, or you can import it with a single token and let Pathrule write the pieces onto the right paths for you. ## The reference token Every pattern has a reference token of the form: ```text ::pathrule:package: ``` For example, the Next.js App Router pattern is `::pathrule:package:nextjs-app-router`. The token is shown on each catalog page, ready to copy. The `::pathrule:` prefix is a reserved namespace. It is matched before the `::skill-name` invocation path, so a pattern token is never mistaken for a skill and never triggers skill discovery. That separation holds across every client, including the offline prompt hook. ## Importing by token To add a pattern, paste its token into your AI assistant in a connected workspace. From there Pathrule does the rest: 1. **It recognises the token.** When Pathrule builds the context for your prompt, it detects the `::pathrule:package:` marker and surfaces an import directive for that slug. 2. **It previews before writing.** A dry-run resolves the pattern and returns its pieces and the paths it intends to use, without changing anything yet. This preview also reports the pattern's declared stack, so the assistant can line the pattern up against your actual project. 3. **It picks paths that match your tree.** A pattern declares suggested paths, but real repositories differ. The assistant chooses a base that matches your layout and re-roots the pattern's paths under it, so the pieces land where they actually belong. 4. **It confirms on a mismatch.** If the pattern targets a stack your project does not appear to use, for example a React Native pattern in a project with no Expo, the assistant asks you to confirm before writing rather than importing blindly. 5. **It writes the bundle.** On confirmation, each piece is created through the normal write path: a memory becomes a memory, a rule becomes a rule with its scope, priority and enforcement, and a skill becomes an invocable skill. Missing nodes along each path are created on demand. After import, the pieces are ordinary workspace content. They surface through the same hooks and retrieval as anything you wrote yourself, and you edit them the same way. ## Importing by manual copy You do not need the token to use a pattern. Each catalog page has a manual copy action that copies the full bundle as plain markdown, with every piece labelled by kind and target path. Paste that into your assistant, or into your own notes, and recreate the pieces wherever you want. This path works today with no setup. Every pattern is also available as raw markdown at `/patterns//raw`, which is convenient when you want an assistant to read the whole bundle from a link. ## Seed, not subscribe Importing a pattern is a one-time seed. The copy in your workspace is yours from that moment on; it does not stay linked to the catalog and it will not change underneath you. When a pattern publishes a newer version, that surfaces as an explicit "new version available" prompt so you can review the difference and decide, never as a silent sync over content you may have already adapted. ## Re-importing and removing - **Re-import is idempotent.** Running the same import again skips pieces that already exist and reports what was added, so you never end up with duplicates. - **Removal is one step.** Because a pattern's definition is its own manifest of titles and paths, a single remove call can undo the whole bundle at once. Imported pieces are tagged with their source pattern, so removal targets exactly what the import created and leaves your own content untouched. ## Where it works Import behaves the same across the engines Studio runs. Cursor, Windsurf and GitHub Copilot use the same flow through Pathrule CLI, while cloud-only clients can use Remote MCP. Clients that cannot inject prompt context rely on the context request and protocol guidance to learn the same import and remove workflow. ## What to read next - [Patterns overview](/docs/patterns/overview) for the bigger picture. - [Anatomy of a pattern](/docs/patterns/anatomy) for what is inside a bundle and how versioning works. - [How hooks work](/docs/hooks/how-hooks-work) for how imported pieces are delivered once they are in your workspace. ## /docs/teams/real-time-collaboration # Real-time collaboration Pathrule is a shared knowledge layer, so two people will eventually edit the same memory, rule, or skill at the same time. The short version: changes sync live, overlaps are caught when you save rather than after you have lost work, and you decide how to resolve them. This page covers how live sync behaves, how an overlapping edit is detected, and the three ways to resolve a conflict. ## Live sync When anyone on your team writes or updates a memory, rule, or skill, the change propagates to the rest of the team within a couple of seconds. This is not a manual refresh. - **Other people's UI updates on its own.** A teammate's new memory shows up in your sidebar without a reload. - **The MCP context that AI clients read updates too.** The context an external client such as Claude Code or Cursor pulls in is kept current, so the next time an assistant asks for context on that path it gets the fresh version, not a stale copy. The two surfaces stay in step on purpose. The same write a teammate makes in the UI is the one your assistant reads through MCP, and the other way around. There is no private cache that drifts apart. ## Overlap detection at save time Pathrule does not lock an item while someone has it open. Locking would stall the team for edits that never actually collide. Instead, every save carries a version token (the same token described in [Writing memories](/docs/content/memories)), and overlap is detected only when two saves target the same starting version. Two things follow from that. | Situation | What you see | |-----------|--------------| | You open an item, a teammate saves a change to it, you have unsaved edits | A stale-base warning before you save, so you know your starting point is no longer current | | You open an item, a teammate saves a change, you have no unsaved edits | The newer version loads in place, with nothing to resolve | | You save and your starting version is still current | The save goes through normally | | You save but your starting version is stale and you have edits | A conflict, resolved with the choices below | The warning is not the conflict. It is an early heads-up that the item moved under you. The actual conflict only appears at the moment you try to save against a version that is no longer the latest. Because the check is scoped to the individual item, teammates editing different memories never block each other. ## Resolving a conflict When a save hits a conflict, Pathrule keeps your local edits in the editor and shows both versions side by side: yours and the current one in the cloud. You then pick one of three resolutions. | Choice | What it does | |--------|--------------| | Keep mine | Saves your version over the current cloud version. This discards the other person's change, so it asks you to confirm first. | | Take theirs | Loads the current cloud version and drops your local edits. It asks you to confirm first. | | AI merge | Combines both versions and returns an editable result you approve before it saves. | The two destructive options never fire silently. Keep mine and take theirs each ask for explicit confirmation, and until you choose, your unsaved work stays in the editor. ## AI merge AI merge is for the common case where two people changed different parts of the same item and you want both, not one or the other. - It is a three-way merge. The merge works from the common version both of you started from, plus your edit and the cloud edit, so it can tell what each person added rather than guessing from the two end states alone. - It returns a draft, not a final write. The merged text appears in its own pane and you can edit it before accepting. Nothing is saved until you approve it. - When both edits add distinct content, the result keeps both. When both touch the same line, the merge reconciles them into one coherent version for you to review. AI merge runs on Pathrule's own AI access, not your personal key. Your source code is not involved in a merge. The merge operates on the conflicting text of the item, the same content already stored in your workspace. ## Change history Every change to a memory, rule, or skill is recorded in a read-only history you can open per item or for the whole workspace. - Each entry shows who made the change, when, and whether it came from a person in the UI or from an AI client. - Entries produced by AI merge are labeled as such, so a merged version is never indistinguishable from a hand-edit. The history is for visibility. It tells you how an item reached its current state, which is the same question the [self-audit](/docs/content/suggestions) helps answer when knowledge starts to drift. ## What to read next - [Writing memories](/docs/content/memories) for how the version token works on a single item. - [Suggestions and self-audit](/docs/content/suggestions) for how stale or conflicting knowledge gets flagged. - [MCP overview](/docs/mcp/overview) for how external AI clients read the synced context. ## /docs/teams/roles-and-permissions # Roles and permissions Pathrule starts as a solo tool and grows into a team product. When you invite colleagues, the question becomes who can see and change what. This page covers the roles you assign, how access narrows from organization to workspace to a single path, and where the check actually runs. The short version: roles are assigned at the organization level, access can be narrowed per workspace and per path, and every read and write is checked by the database against your signed-in user. The same check applies whether the request comes from Pathrule Web, Pathrule Studio, Pathrule CLI, or the MCP server an AI client speaks. ## The four roles Roles are assigned per person at the organization level. An admin invites a colleague by email and picks their role; the colleague accepts the invite to join. | Role | Can do | | --- | --- | | **Owner** | Everything an admin can, plus transfer ownership. There is always exactly one owner, and the owner cannot be removed. | | **Admin** | Invite and remove members, change member and viewer roles, switch workspaces between organization-wide and private, and set per-node permission overrides. | | **Member** | Read and write content (memories, rules, skills) wherever they have access. The everyday contributor role. | | **Viewer** | Read content wherever they have access. No writes. | A few guardrails follow from this: - An admin can change member and viewer roles, but cannot promote anyone to admin or change another admin. Only the owner does that. - An organization always keeps at least one admin. The last admin cannot be removed or demoted. - Transferring ownership is a deliberate, two-step action, and the previous owner becomes an admin. Role changes and ownership transfer require a fresh re-authentication, so an old, ambient session cannot quietly escalate access. ## Workspace access: organization-wide or private A role sets what a person can do. A workspace's access mode sets who can reach it at all. Each workspace is one of two modes. - **Organization-wide.** Every member of the organization has access, at their org role. - **Private.** Only people explicitly added to the workspace have access. Org membership alone is not enough. When you switch a workspace to private, Pathrule auto-adds the current org members first, then lets the admin remove whoever should not be there. The default is no accidental lockout: you take access away on purpose rather than risk cutting someone off by surprise. Inside a private workspace, a person's workspace role overrides their org role, so you can give someone a different level of access there than they have elsewhere. ## Per-node overrides that cascade Inside a workspace, knowledge attaches to repository paths. Permissions can attach to those same paths. A workspace admin can pin an override on any node that grants or removes access for a specific member, more narrowly than their workspace role would imply. An override controls, per member: - **Read** access to the node. - **Write** access, split by content type: memories, rules, and skills. Overrides cascade. An override set on `/src/core` applies to that node and to everything beneath it (`/src/core/utils`, `/src/core/models`, and so on) unless a descendant node carries its own override that says otherwise. The closest override down the tree wins, the same way the most specific memory wins. This lets you keep a workspace open by default and lock down one sensitive subtree, or do the reverse. Because overrides resolve top-down with inheritance, the effect on any single path is predictable: start from the workspace role, apply the nearest override on the way down, and that is the access. ## Losing access is non-destructive Permission changes never destroy work and rarely hide it. - **Lose write access to a path** and the editor opens read-only with a banner that says so. Nothing disappears. You can still read everything you could before. - **Lose read access to a path** and only then does its content drop out of view. Removing read access is the one way to hide a node from a member. The same boundary reaches the assistant. When an AI client tries to write to a node a member cannot write, the MCP tool call comes back with a clear permission-denied result the assistant can relay to you in plain language, rather than failing silently or appearing to succeed. The path-scoped context an assistant receives, and the CLAUDE.md it reads, reflect only the nodes that member can actually read. ## Where the check runs None of this is enforced in the application you happen to be using. Every read and write runs through a database access check resolved against your signed-in user, your organization membership, and any node-level overrides. The application layer cannot bypass it. - **One check for every surface.** Pathrule Web, Pathrule Studio, Pathrule CLI, and the MCP server all go through the same database-enforced access control. A change in the browser and a write from an AI client are gated by the same rules. - **No shared admin key.** Each surface carries a short-lived, per-user token, never a shared service key that could unlock another team's data. A leaked client can only ever reach what that user already can. - **Server-side resolution.** Membership and per-node overrides are resolved on the server, not trusted from the client, so an edited request cannot grant itself access it was not given. For the full picture of how the cloud is gated, see the [security overview](/security). ## On self-hosted Enterprise self-hosted runs the same role and permission model on your own infrastructure. The roles, the workspace access modes, and the cascading per-node overrides behave the same way; the difference is that the data and the database live on your side. Sign-in goes through your own identity provider over SSO, and those identities map onto the same organization roles described here. See [Enterprise self-hosted](/docs/editions/self-hosted) for how that deployment works. ## What to read next - [Writing memories](/docs/content/memories) for the content these permissions apply to. - [Core concepts](/docs/start/core-concepts) for the workspace tree paths attach to. - [MCP overview](/docs/mcp/overview) for how an AI client reads and writes through the same enforced access. ## /docs/teams/team-profiles # Who is the reference for what An assistant that knows your codebase can still get one thing badly wrong: it decides something that was not its call. It renames a public field, changes a pricing rule, restructures a module, and it does so with no idea that a person on the team is the reference for that area and would have answered in one sentence. Team member profiles close that gap. Each person in your organization gets a profile that answers a single question, who is the reference for which area, and a short version of that answer is compiled into what every agent reads before its first tool call. ## A profile belongs to the team, not to a repository The profile is organization scoped and workspace independent. Someone who is the reference for payments is the reference for payments whether the work happens in the API repository, the mobile app, or a service that did not exist last month. Tying it to one workspace would mean re-establishing the same fact per repository, which is how a directory goes stale. ## Two halves, and only one of them is inferred A profile has a derived half and a declared half, and the split is deliberate. **Derived: the areas you actually work in.** Pathrule already records a short entry per piece of work, and it already knows who authored which memory and rule at which path. Those two counts, work logged against a path and knowledge authored at that path, are the evidence. Nothing else is read: not your code, not your commit messages, not how long anything took. The window rolls, so an area you left behind fades out of your profile instead of following you for years. **Declared: your decision scope.** This one is typed by the person and never derived. Authority over a product decision does not follow from touching files, and a system that inferred it from activity counts would be inventing it. The person who touched the billing code most last month may be the last person who should be deciding a pricing rule. So Pathrule asks instead of guessing. The same rule covers your display name, your pronouns and how available you are: your own words, in your own row. ## You see your own profile, and you can correct it The Members panel in Studio shows the team, and it shows you your own profile the way an agent will read it. A derived list you disagree with is not something to file a request about: you replace it with your own list of areas or tags, and yours wins. The presence of your list is what marks the answer as corrected rather than inferred, so nothing quietly overwrites it on the next derivation. The database enforces the boundary rather than the interface. You can write your own row and nobody else's. ## What the agent actually gets Not the profile table. A short block, appended to the instruction files your agents read first, that looks like this in substance: - the team name, and the person the file belongs to, with up to three of their own areas - up to three colleagues, each with the single area they are the reference for - up to two declared decision scopes - one instruction: address the user by name, and when a decision touches another person's area, point at its owner instead of deciding for them That last line is the point of the whole feature. A list of names with no instruction is data an agent scrolls past. So the instruction is reserved before anything else is measured, and if the block would end up with the instruction and nobody to point at, the block is dropped entirely rather than shipped as noise. ## What the block cannot say The block accepts names, paths, tags and a declared scope. There is no field for a performance claim, a speed claim, a quality claim or a seniority claim, and free text is capped in length and collapsed to a single line. This is structural rather than a review guideline: a compiled instruction file cannot grow a paragraph of opinion about a colleague here, because there is nothing for such a sentence to travel in. It is also small on purpose, a fixed budget of around a hundred tokens including its heading. When there is more to say than the budget allows, whole lines are dropped from the least valuable end rather than a sentence being cut in half, so a trimmed block still reads as something an agent can act on. One block, once per file, never a second one. ## Why it rides the compiled file Pathrule has two ways to reach an agent: the compiled instruction files, read once at the start of a session, and the [per-turn hook](/docs/hooks/how-hooks-work), which reaches the model on every prompt. The hook is the right channel for what changes with the request. This block does not change with the request, so paying for it on every prompt of a long session would be paying many times for one constant fact. It sits at the very end of the file for a related reason. A cached instruction prefix is invalidated from the first changed byte onward, and team membership changes far more often than your workspace knowledge does. Keeping the volatile block last leaves everything above it byte identical when somebody joins. ## Consent Visibility is per person and defaults to being visible to your team. Setting your profile to private removes you from every team-facing read, including the compiled block, so no agent on the team is told what you are the reference for. The choice lives in the same row the profile does and the database applies it to every query, so there is no surface where a private profile leaks because one screen forgot to filter. ## What to read next - [Roles and permissions](/docs/teams/roles-and-permissions) for who can read and change what in a workspace. - [How hooks work](/docs/hooks/how-hooks-work) for the other channel, the one that carries what changes per prompt. - [What an AI session records](/docs/content/activity-log) for the activity entries the derived half is counted from. ## /docs/mcp/overview # MCP overview Pathrule speaks the Model Context Protocol. The protocol is what your AI coding assistant uses to call into external tools and read external state. Pathrule shows up to the assistant as a normal MCP server, so any client that can speak MCP can use it. There are two ways to connect. The local server runs inside Pathrule Studio or Pathrule CLI: the assistant talks to it over stdio, and the runtime talks to the Pathrule cloud over HTTPS. For cloud-only clients that cannot run a local runtime, a hosted Remote MCP endpoint accepts a direct connection over streamable-http with scoped access to your workspace. Shared tools keep the same contract, while each runtime advertises explicit additions through `tools/list`. In both cases Pathrule has no tool that reads your filesystem, so your source code stays on your machine. ## What the server exposes Pathrule's MCP surface is typed and grouped around the data model. The core tools below cover everyday context, content and activity flows; the [tools reference](/docs/mcp/tools-reference) is the canonical inventory. ### Read tools - `pathrule_get_context`. The primary entry point. Given the current working directory and the user's intent, it returns the right slice of memories, rules, and skills for that path. The response carries the workspace overview, the rules and memories that already match, and a hint about what to read next. - `pathrule_read_memory`, `pathrule_read_rule`, `pathrule_read_skill`. Fetch the full body of a specific node by id when the assistant wants to cite or follow it. - `pathrule_get_tree`, `pathrule_get_node`. Inspect the workspace structure or a specific node. - `pathrule_list_memories`. Enumerate the memories under a path, useful for discovery prompts. ### Write tools - `pathrule_write_memory`, `pathrule_write_rule`, `pathrule_write_skill`. Create content at a workspace path. Missing nodes along the path are created on demand. - `pathrule_update_memory`, `pathrule_update_rule`, `pathrule_update_skill`. Edit an existing record. Optimistic concurrency is enforced with a version id. - `pathrule_delete_memory`, `pathrule_delete_rule`, `pathrule_delete_skill`. Soft delete with a thirty day undo window. ### Activity and housekeeping - `pathrule_log_activity`. Called after any file modifying response so the team can see what the assistant did and where. - `pathrule_goto`. Move the assistant's working node when the user asks for content from a different scope. - `pathrule_ping`. A health check used by the CLI doctor. ## How hooks fit in Hooks are how Pathrule keeps the assistant fast. Before the assistant's first tool call in a turn, the hook supervisor reads a cached slice for the current working directory and hands it to the editor as system context. This avoids a synchronous MCP round trip for the common case. When the hook is enough, the assistant does not need to call `pathrule_get_context`. It already has the right slice. MCP tools are reserved for two scenarios. 1. The assistant wants more than the hook surfaced. For example, a discovery prompt that needs the full memory body, or a refactor that touches a path the hook did not anticipate. 2. Something is worth keeping. The assistant proposes a memory, rule, or skill and writes it once you confirm, or you ask it to write one directly. Writes go through the write tools, and nothing is saved without your okay. See [How hooks work](/docs/hooks/how-hooks-work) for the underlying mechanics. ## Studio agents and CLI integrations Pathrule Studio is the main product. It runs Claude Code, Codex, Grok, Kimi, Antigravity and OpenCode inside one workspace. Pathrule CLI is the lighter route for external clients that connect to the same context layer over MCP. - **In Pathrule Studio**: Claude Code, Codex, Grok, Kimi, Antigravity and OpenCode run natively and can be switched mid-conversation. - **Through Pathrule CLI**: Cursor, Windsurf and GitHub Copilot receive the same memories, rules and skills as external integrations. - **Claude Code and Codex outside Studio**: the CLI can also wire their standalone clients when you prefer a terminal workflow. - **Any other MCP client**: connects over stdio. Add the Pathrule MCP command to your client's config and it will see the same tool surface. - **Cloud-only clients**: an AI client that cannot run a local runtime connects to the hosted Remote MCP endpoint over streamable-http instead, with scoped access to your workspace. ## What to read next - [How hooks work](/docs/hooks/how-hooks-work) for what happens between the cache and the editor. - [Core concepts](/docs/start/core-concepts) for the data model the tools operate on. - [CLI install](/docs/cli/install) for setting up the runtime that hosts the server. ## /docs/mcp/one-contract # One contract, every surface Pathrule exposes one Model Context Protocol contract. Every shared tool keeps the same name, arguments and response shape wherever it is available. A surface can add capabilities that only make sense there, such as hosted workspace setup on Remote MCP or simulator control inside Studio, without changing the shared tools underneath. The short version: pick the entry point that fits your machine and your AI client. The common tools and workspace stay stable, and `tools/list` tells the truth about the additions that surface can actually execute. ## The surfaces Pathrule Studio and Pathrule CLI are local runtimes. They host the MCP server on your machine and your assistant talks to it over stdio. The runtime talks to the Pathrule cloud over HTTPS. The VS Code extension is a third local entry point. It runs the same bundled CLI server and connects Cursor, Windsurf and GitHub Copilot, so the agent in your editor reaches the same tools with no JSON to hand-edit. It can also wire standalone Claude Code and Codex. Cursor and Windsurf are VS Code forks, so the extension is available to them too. Pathrule Web is the browser management console for your organization, members, billing, workspaces and usage. It is cloud-only and does not touch your filesystem. You author knowledge and run agents in Pathrule Studio, not in the browser. Pathrule Remote MCP is a hosted endpoint at `https://mcp.pathrule.io/mcp`. AI clients that can only reach a cloud connector authenticate with OAuth and call the cloud-safe part of the same contract over streamable-http. There is nothing to install. ## Shared tools keep one shape The read tools (`pathrule_get_context`, `pathrule_read_memory`, `pathrule_read_rule`, `pathrule_read_skill`, `pathrule_get_tree`, `pathrule_get_node`, `pathrule_list_memories`) and the write tools (`pathrule_write_memory`, `pathrule_write_rule`, `pathrule_write_skill`, and their update and delete counterparts) keep the same names and shapes across the surfaces that expose them. The same holds for activity and refresh tools. An integration can therefore reuse a shared tool without translating a second API. Availability is capability-based. The local stdio server adds efficient local workflow tools such as batch read and name resolution. Remote MCP adds organization, workspace and snapshot operations that require a hosted account boundary. Studio can add design, task, run and simulator bridges because it owns those live surfaces. The [MCP tools reference](/docs/mcp/tools-reference) inventories these groups explicitly. See [MCP overview](/docs/mcp/overview) and the [MCP tools reference](/docs/mcp/tools-reference) for the full list. ## Local and remote boundaries Local runtimes know your working directory and active file, so context can arrive before the first tool call through client-native delivery. The remote endpoint has no cwd to read, so workspace-scoped tools take an explicit `workspace_id` and protocol text is sent by default. No Pathrule MCP surface has a tool that reads your source files. On local surfaces your code never leaves the machine and only team-written content is stored in the cloud. The remote endpoint is cloud-only by design: it cannot read local files or run hooks, the same boundary as Pathrule Web. ## Tool-agnostic, low lock-in Pathrule Studio runs Claude Code, Codex, Grok, Kimi, Antigravity and OpenCode as its primary agents. Pathrule CLI is the lighter integration route for Cursor, Windsurf and GitHub Copilot, and any client that speaks MCP can connect by adding the Pathrule MCP command to its config. Because the contract is plain MCP, you are not committing to one editor or one vendor. Switch agents, add a teammate on a different client, or move from a local runtime to the hosted endpoint, and the tools and the workspace stay the same. Verify it yourself: point an MCP client at a Pathrule runtime and run `tools/list`. Shared `pathrule_` tools retain their contract, and surface-specific tools appear only where their required capability exists. ## Which entry point Choose by where you work and what your client supports. | Surface | Reach the contract by | Best for | | --- | --- | --- | | Studio (macOS) | Local stdio server in a native app | Coding with Claude Code, Codex, Grok, Kimi, Antigravity and OpenCode, authoring knowledge, the full workbench | | CLI | Local stdio server from the terminal | Cursor, Windsurf and GitHub Copilot integrations, terminal-first setup, scripts, CI, SSH | | VS Code (and forks) | Bundled local server, one-command agent wiring | The editor you already use, with no hand-edited config | | Web | Cloud management console | Organization, members and roles, billing, workspace admin, usage | | Remote MCP | Hosted OAuth endpoint over streamable-http | Clients that only reach a hosted connector, or a fresh machine | Cloud content is shared across every surface and one sign-in follows you between them. Local runtime state stays scoped to the current user and machine. ## What to read next - [MCP overview](/docs/mcp/overview) for how Pathrule exposes its tools and how hooks fit in. - [MCP tools reference](/docs/mcp/tools-reference) for the full tool list and arguments. - [Pathrule Web](/docs/surfaces/web) for the browser management console that shares the same cloud. ## /docs/mcp/claude-code # Claude Code Claude Code is one of the primary agents Pathrule Studio runs natively. If you use standalone Claude Code outside Studio, Pathrule CLI provides two integration layers: hooks that push path scoped context before a tool call, and MCP tools that Claude can pull from when it wants more. This page covers what gets written into your project, how the two layers fit together, and how to verify the integration end to end. ## Two layers, one workspace - **Hooks (push).** On `PreToolUse`, `UserPromptSubmit`, and `PostToolUse`, Claude Code invokes Pathrule's hook supervisor. The supervisor reads a precomputed slice from the local cache and returns it as context. No network call in the hot path. - **MCP tools (pull).** When the hook payload is not enough (discovery prompts, full memory bodies, writes), Claude calls the Pathrule MCP server directly through tools like `pathrule_get_context` and `pathrule_write_memory`. Hooks are the default. MCP tools are the deep path. The same content tree drives both. ## Companion files When you install Pathrule into Claude Code, three files appear in your project. - **`CLAUDE.md`.** The workspace overview Claude reads at session start. Includes the protocol summary and a router to the deeper Pathrule MCP. - **`.claude/settings.json`.** The Claude Code config. Pathrule writes the MCP server entry and the hook registrations here. - **`.claude/rules/pathrule-protocol.md`.** A small protocol file the assistant reads to understand how to interact with Pathrule (when to call `pathrule_get_context`, when to write memories, what `::skill-name` means). Skills attached to your workspace are also materialized into `.claude/skills//SKILL.md` so Claude can invoke them by name. ## Rule enforcement A rule has two independent settings: a priority (high, medium, low) that ranks how it surfaces, and an enforcement mode (advisory or strict) that decides whether it can block. Blocking is driven by enforcement, not by priority. - On `PreToolUse`, the hook checks the upcoming tool call against strict rules that define a matching pattern. - If a strict rule matches and the call would violate it, the hook blocks the call before it runs and returns the rule as the reason. - Claude Code stops, surfaces the reason to the user, and asks for guidance. Advisory rules do not block. They ride along as context and the assistant decides how to apply them. Strict enforcement runs through the local hook on Claude Code; the Remote MCP surface has no hooks, so it surfaces rules as context only. ## Install Through Pathrule Studio: 1. Open the app, attach your workspace to the local directory. 2. Open the AI clients tab, enable Claude Code. 3. The app writes the configs and registers the hooks. Through Pathrule CLI: ```bash pathrule install claude pathrule sync pathrule doctor ``` The doctor confirms the hooks are wired, the MCP server is reachable, and `CLAUDE.md` is current. ## Verify Open Claude Code in a directory you attached. Start a new turn. The Pathrule section should appear in the context surface before the first tool call, listing the path it resolved, the matching rules, the strongest memory bodies and any less-certain candidates by title. If nothing appears, run: ```bash pathrule doctor --client claude ``` The doctor reports which step is off: missing config, stale cache, hooks not registered, MCP server unreachable. ## When Claude writes content Claude can write memories, rules, and skills back into Pathrule using the MCP write tools. The runtime tags the source as `claude` so you can see in the UI which content was AI authored. Use the `pathrule_log_activity` tool to make every file modifying response visible in the activity log. This is the bridge between what Claude did and what your team sees. ## What to read next - [How hooks work](/docs/hooks/how-hooks-work) for the model behind the push layer. - [MCP overview](/docs/mcp/overview) for the pull layer. - [MCP tools reference](/docs/mcp/tools-reference) for every tool Claude can call. ## /docs/mcp/codex # Codex CLI Codex is one of the primary agents Pathrule Studio runs natively. For standalone Codex CLI outside Studio, Pathrule CLI integrates through two pieces: a companion `AGENTS.md` file at the workspace root, and the same MCP tool surface the other clients use. This page covers what gets written into your project for the integration, how it differs from the Claude Code and Cursor flows, and how to verify it. ## What Pathrule writes When you install Pathrule into Codex CLI, you get: - **`AGENTS.md`** at the workspace root. The protocol document Codex reads at session start. Updated when Pathrule cloud state changes. - **An MCP server entry** in Codex's config so the assistant can call `pathrule_*` tools. - **Materialized skills** attached to your workspace so Codex can invoke them by name. `AGENTS.md` is the analogue of `CLAUDE.md` for Codex. Same workspace overview, same protocol, same router into the MCP server. ## Hook coverage Codex's hook contract is close to Claude Code's. Pathrule registers session-start, pre-tool, post-tool, and prompt-submit hooks, so Codex receives the path-scoped context on each prompt and tool call, and a strict rule can block a matching change at the pre-tool hook. `AGENTS.md` stays current so the assistant also sees the protocol at session start. The main differences from Claude Code are in the tool surface: Codex uses its `apply_patch` format (with `*** Update File:` markers) instead of separate Edit and Write tools, and there is no Read hook. Pathrule's shared hook script understands `apply_patch` and resolves the affected paths back to workspace nodes. The investment lives in the content layer, not in the client, so the same memories, rules and skills serve Codex and every other client. ## Per client isolation Codex coexists with Claude Code and Cursor on the same machine. You can install one, two, or all three. They share the same Pathrule workspace, the same MCP server, and the same content tree. The configs each client reads are independent. ## Install Through Pathrule Studio: 1. Open the AI clients tab, enable Codex CLI. 2. The app writes `AGENTS.md` and the MCP entry, and materializes skills. Through Pathrule CLI: ```bash pathrule install codex pathrule sync pathrule doctor --client codex ``` ## Verify Open Codex CLI in a directory you attached to a workspace. The assistant should read `AGENTS.md` at session start and be able to call `pathrule_get_context` against your working directory. Run a simple prompt that touches a path with content. The assistant should be able to surface that content through MCP. If it cannot, run: ```bash pathrule doctor --client codex ``` The doctor reports whether the MCP server is reachable, whether `AGENTS.md` is up to date, and whether the runtime can resolve your working directory to a workspace. ## What stays the same The content layer is identical across clients. - The same memory shows up to Codex through the MCP tools that shows up to Claude Code through the hook. - A strict rule still blocks if the assistant tries to violate it through the hook path. - A skill is invokable by name. If your team writes content for one assistant, every assistant gets it. ## What to read next - [Claude Code](/docs/mcp/claude-code) for the sibling integration with native hooks. - [Cursor](/docs/mcp/cursor) for the Cursor integration. - [MCP tools reference](/docs/mcp/tools-reference) for every tool Codex can call. ## /docs/mcp/cursor # Cursor Cursor is a lighter external integration connected through Pathrule CLI. The CLI uses Cursor's native hook system and MCP support to deliver the same path scoped context, rule enforcement and tool surface that Studio's primary agents use. This page covers what Pathrule writes into your project for Cursor, how the hook events map across clients, and how to verify the integration. ## What Pathrule writes When you install Pathrule into Cursor, you get: - **`.cursor/hooks.json`.** Cursor's native hook configuration. Pathrule registers the events it cares about here. - **`.cursor/mcp.json`** (or equivalent MCP config). Points Cursor at the local Pathrule MCP server. - **Materialized skills.** Skills attached to your workspace appear in the project so Cursor can invoke them by name. No third party Skills toggle is needed. Cursor sees the CLI-managed Pathrule hook provider directly. ## Hook event coverage Cursor's events map to Pathrule's three injection points: - **`preToolUse`.** Before Cursor runs a tool. This is where a strict rule blocks a matching tool call. On Cursor this event carries the block decision; the path scoped context is delivered through `sessionStart` and `postToolUse` instead. - **`postToolUse`.** After a tool finishes. Pathrule uses this both to capture activity and as the compensation point for context that Cursor's `beforeSubmitPrompt` does not carry. - **`sessionStart`.** When a new session begins. Pathrule returns the workspace overview so Cursor sees the same shape Claude Code sees from `CLAUDE.md`. A single shared hook script handles the event shape differences between Cursor and Claude Code. You do not need to think about it: install Cursor through Pathrule and the right shape lands. ## Per client isolation Pathrule supports any combination of AI clients on a single machine. - **Cursor only.** Pathrule writes only the Cursor configs. - **Claude Code only.** Pathrule writes only the Claude Code configs. - **Both.** Pathrule writes both. The hooks register independently, the MCP server is shared, the content tree is the same. The choice is whatever the user picks in Pathrule Studio's AI clients tab, or whichever clients you install via `pathrule install`. ## Install Through Pathrule Studio: 1. Open the AI clients tab, enable Cursor. 2. The app writes `.cursor/hooks.json`, the MCP entry, and any attached skills. Through Pathrule CLI: ```bash pathrule install cursor pathrule sync pathrule doctor --client cursor ``` ## Verify Open Cursor in a directory you attached to a workspace. Open the Hooks Settings tab to confirm Pathrule appears as a registered provider. Start a new chat. The path scoped context should show up before the first tool call. If the integration is silent: ```bash pathrule doctor --client cursor ``` The doctor reports which step is off: missing `.cursor/hooks.json`, MCP not reachable, or hook script not executable. ## What stays the same Everything you write in Pathrule reaches Cursor with the same shape it reaches Claude Code. - A memory written in Studio or through MCP shows up in both. - A strict rule blocks matching tool calls in both. - A skill is invokable by name in both. - The MCP tools (`pathrule_get_context`, `pathrule_write_memory`, etc.) behave identically. If you ship a feature for one assistant, you get it for the other. ## What to read next - [Claude Code](/docs/mcp/claude-code) for the sibling integration. - [How hooks work](/docs/hooks/how-hooks-work) for the underlying model. - [MCP tools reference](/docs/mcp/tools-reference) for every tool the assistant can call. ## /docs/mcp/windsurf # Windsurf Windsurf is a lighter external integration connected through Pathrule CLI. The CLI writes a local MCP server entry plus a companion instruction file that Windsurf reads at session start, giving it the same path-scoped knowledge as Studio's primary agents. This page covers what Pathrule writes into your project for Windsurf, why the same content reaches Windsurf as every other tool, and how to verify the integration yourself. ## What Pathrule writes When you install Pathrule into Windsurf, you get: - **An MCP server entry** in Windsurf's config. It points the assistant at the local Pathrule MCP server so it can call the `pathrule_*` tools. - **A companion instruction file** rendered in the format Windsurf reads. It carries the workspace overview and the Pathrule protocol, the same substance the other clients get in their own native formats. - **Materialized skills** attached to your workspace, so Windsurf can invoke them by name. The companion file is not hand-copied per client. Pathrule generates it from a shared renderer that also produces the Claude Code, Cursor, and Codex instructions, so the four stay in sync instead of drifting apart over time. ## How the content reaches Windsurf Any tool that speaks MCP can use Pathrule over stdio: add the Pathrule MCP command to the client config, and the assistant sees the same tool surface. For Windsurf, Pathrule CLI writes that config and renders the companion file alongside it. The companion file delivers the workspace overview and protocol at session start; the MCP tools deliver everything deeper on demand. Two facts make this work without per-client divergence. - **One tool contract.** The MCP tools (`pathrule_get_context`, `pathrule_read_memory`, `pathrule_write_memory`, and the rest) are the same set Claude Code and Cursor call. The assistant fetches context and writes memories, rules, and skills through the identical surface; the client config is the only thing that changes. - **One source of truth.** The companion file and the materialized skills are rendered views, not the canonical copy. A memory written in Studio or through MCP reaches Windsurf with the same shape it reaches every other client. Pathrule has no tool that reads your filesystem. Your source code stays on your machine; only the team-written content (memories, rules, skills) is stored. ## One content layer, many delivery formats The instruction format each client reads differs, so Pathrule produces every companion file from the same shared renderer rather than hand-copying one per tool. That keeps the Windsurf protocol identical in substance to the Claude Code, Cursor, and Codex versions, even though the file format differs. The investment lives in the content layer, not in the client. The same memories, rules, and skills serve Windsurf and every other client without rewriting anything. ## Through the VS Code extension Windsurf is a VS Code fork. If you run the Pathrule VS Code extension inside Windsurf, the extension detects the host and writes the same managed MCP entry through the installer that the CLI and Studio use, with no hand-edited JSON. That entry points at the bundled Pathrule runtime and never carries secrets. This is one more entry point to the same workspace, not a separate integration. See [Pathrule for VS Code](/docs/surfaces/vscode) for what the extension does and [One contract, every surface](/docs/mcp/one-contract) for why the tool surface stays identical across every surface. ## Per client isolation Windsurf coexists with Claude Code, Cursor, and Codex on the same machine. You can install one client, several, or all of them. - They share the same Pathrule workspace, the same MCP server, and the same content tree. - The configs each client reads are independent. Installing Windsurf does not touch the others. - Removing one client leaves the rest, and the content, untouched. The choice is whatever you pick in Pathrule Studio's AI clients tab, or whichever clients you install with `pathrule install`. ## Install Through Pathrule Studio: 1. Open the AI clients tab, enable Windsurf. 2. The app writes the MCP entry, renders the companion file, and materializes any attached skills. Through Pathrule CLI: ```bash pathrule install windsurf pathrule sync pathrule doctor --client windsurf ``` ## Verify Open Windsurf in a directory you attached to a workspace. The assistant should read the companion file at session start and be able to call `pathrule_get_context` against your working directory. Run a prompt that touches a path with content. The assistant should surface that content through the MCP tools. If it cannot: ```bash pathrule doctor --client windsurf ``` The doctor reports which step is off: a missing MCP entry, a server that is not reachable, or a working directory the runtime cannot resolve to a workspace. ## What stays the same The content layer is identical across clients. - The same memory that shows up to Claude Code through the hook shows up to Windsurf through the MCP tools. - A rule reaches Windsurf through the companion file and MCP. Local pre-write blocking is available on hook-capable clients such as Studio, Claude Code, Cursor, Codex and GitHub Copilot. - A skill is invokable by name. - The MCP tools behave identically. If your team writes content for one assistant, every assistant gets it. ## What to read next - [Cursor](/docs/mcp/cursor) for the sibling VS Code-fork integration with native hooks. - [One contract, every surface](/docs/mcp/one-contract) for why the tool surface is the same everywhere. - [Pathrule for VS Code](/docs/surfaces/vscode) for the extension that can register Windsurf from inside the editor. - [How hooks work](/docs/hooks/how-hooks-work) for the delivery model behind the content. ## /docs/mcp/copilot # GitHub Copilot GitHub Copilot is a lighter external integration connected through Pathrule CLI. It receives the same path scoped context, rule enforcement and MCP tool surface as Studio's primary agents. Copilot is unusual because one repo level file set feeds three surfaces at once: VS Code agent mode, the Copilot CLI and the coding agent. This page covers what Pathrule writes for Copilot, how the surfaces differ, how the hook events map, and how to verify the integration. ## What Pathrule writes When you enable Copilot, Pathrule writes Copilot's own paths rather than inventing new ones. Every file lives under `.github/`, which is where Copilot already looks. | File | What it does | |---|---| | `.github/copilot-instructions.md` | The Pathrule protocol body, auto applied in agent mode and the CLI. | | `.github/instructions/pathrule.instructions.md` | An `applyTo`-scoped pointer that keeps the protocol present even when instruction matching is glob driven. | | `.github/hooks/pathrule.json` | The hook configuration. This is the one hook location all three Copilot surfaces read. | | `.github/skills//SKILL.md` | Skills attached to your workspace, so Copilot can invoke them by name. | Skills have one nuance. Copilot also reads `.claude/skills`. If you have both Claude Code and Copilot enabled on the same workspace, Pathrule skips `.github/skills` so Copilot does not see every skill twice. Enabling both clients produces no duplicated skills and no duplicated protocol in Copilot's context. You can confirm what landed: ```bash cat .github/copilot-instructions.md cat .github/hooks/pathrule.json ``` ## Three surfaces, one file set The same `.github/` files light up each Copilot surface, but the surfaces differ in how hooks and MCP reach them. | Surface | Hooks | MCP config location | |---|---|---| | VS Code agent mode | Reads `.github/hooks`; also reads `.claude/settings.json` when present | User level `mcp.json`, or registered in editor by the Pathrule VS Code extension | | Copilot CLI | Reads `.github/hooks` | `~/.copilot/mcp-config.json` | | Coding agent (on github.com) | Reads `.github/hooks`; runs in a restricted sandbox | Repo Settings, configured by you (not file managed) | For VS Code, the MCP config root key is `servers`, not `mcpServers`. If you use the [Pathrule VS Code extension](/docs/surfaces/vscode), Copilot agent mode is registered for you in the editor, with no MCP file to edit by hand. The coding agent is the one surface Pathrule cannot wire from disk: its MCP servers are set in the repo's Settings on github.com, so `pathrule doctor` prints a short note pointing you there rather than silently doing nothing. ## Hook event coverage Copilot's hook events map to the same three injection points Pathrule uses on Cursor and Claude Code. - **`sessionStart`.** When a session begins. Pathrule returns the workspace overview so Copilot starts with the same shape it would read from an instructions file. - **`postToolUse`.** After a tool finishes. Pathrule delivers the path scoped context for what the agent just touched, and captures activity. - **`preToolUse`.** Before a tool runs. This is where a strict rule blocks a matching tool call before the change lands. The per prompt event is deliberately not wired. Copilot's output for that event carries no additional context, so matching it would spend a process per prompt for no injection. SessionStart plus PostToolUse cover the same ground. The result is parity with the Cursor injection profile. A single shared hook script handles every client. It detects the Copilot payload shape, normalizes it to one canonical form, runs the same rule and memory selection used for every other client, then writes back in Copilot's schema. You do not configure any of this per surface. The script is fail open by construction: an unrecognized or malformed payload returns nothing rather than breaking your Copilot session. ## Install Through Pathrule Studio: 1. Open the AI clients tab, enable GitHub Copilot. 2. The app writes the `.github/` files and the MCP config for the surfaces you use. Through Pathrule CLI: ```bash pathrule install --client copilot pathrule sync pathrule doctor --client copilot ``` Through the Pathrule VS Code extension, choose Copilot in **Connect AI clients**. The extension registers Copilot agent mode in the editor and writes the instruction files and hook config for you. ## Verify Open a workspace you attached to Pathrule and start a Copilot session on the surface you use. - **VS Code agent mode or the Copilot CLI.** Start a new chat. The path scoped context should arrive before the first tool call. Edit a file under a path with attached knowledge and watch the relevant rules and memories surface. Trigger a strict rule and confirm the matching tool call is blocked. - **Coding agent.** The `.github/` files apply in the sandbox without error. Strict rules degrade to a deny in that restricted environment. If the integration is silent: ```bash pathrule doctor --client copilot ``` The doctor reports both MCP configs and whether the hook file is present, and it repairs stale entries. Disabling Copilot removes every file Pathrule owns. ## What stays the same Everything you write in Pathrule reaches Copilot with the same shape it reaches Claude Code and Cursor. - A memory written in Studio or through MCP shows up in Copilot. - A strict rule blocks matching tool calls in Copilot. - A skill is invokable by name in Copilot. - The MCP tools (`pathrule_get_context`, `pathrule_write_memory`, and the rest) behave identically. You write knowledge once and every supported agent reads it. ## What to read next - [Cursor](/docs/mcp/cursor) for the sibling hook integration. - [One contract, every surface](/docs/mcp/one-contract) for why the same tool surface reaches every client. - [How hooks work](/docs/hooks/how-hooks-work) for the underlying delivery model. - [Pathrule for VS Code](/docs/surfaces/vscode) for in editor registration of Copilot agent mode. ## /docs/mcp/tools-reference # MCP tools reference This page inventories Pathrule's MCP tools by capability. The assistant rarely needs all of them. Most sessions touch only `pathrule_get_context` plus one or two reads or writes. Local stdio, hosted Remote MCP and Studio then add only the operations their runtime can actually perform. For the underlying model, see [MCP overview](/docs/mcp/overview). ## Context and discovery | Tool | Purpose | | --- | --- | | `pathrule_get_context` | The primary entry point. Resolves the current working directory to a workspace node and returns the right slice of memories, rules, and skills for the task. | | `pathrule_get_tree` | Returns the workspace node tree (folders, files, contexts). Useful for discovery prompts. | | `pathrule_get_node` | Fetches a single node plus its attached memories, rules, and skills. | | `pathrule_resolve` | Maps a known title or name to an id, path and version handle without walking the tree. A unique match can include the body in the same call. Local stdio. | | `pathrule_read` | Batch reads memory, rule and skill ids in one round trip, up to the server cap. Local stdio. | | `pathrule_goto` | Fuzzy resolves a name or path to a node id. Useful when the user names a target loosely. | | `pathrule_ping` | Health check. Returns the runtime's view of the current working directory and a timestamp. | | `pathrule_setup` | Bootstraps Pathrule in a new repo by proposing initial memories, rules, and skills the user can approve. | Most sessions start and end with `pathrule_get_context`. The response carries the workspace overview, the matching content ids, and a hint about which tool to call next. The assistant follows that hint rather than guessing. ## Memory | Tool | Purpose | | --- | --- | | `pathrule_list_memories` | Enumerates the memories under a path with titles and short previews. The virtual MainMemory index. | | `pathrule_read_memory` | Returns the full body of a memory by id, including the version token for optimistic concurrency. | | `pathrule_write_memory` | Creates a memory at a node path. Missing nodes along the path auto create. Source defaults to `claude` when called over MCP. | | `pathrule_update_memory` | Edits an existing memory. Requires `expected_version_id` so concurrent edits conflict cleanly. | | `pathrule_delete_memory` | Soft deletes a memory. Recoverable for thirty days. | The default flow is `get_context` to find the relevant memory id, then `read_memory` for the body if the assistant needs to cite it, and `write_memory` when the user asks to capture something. ## Rule | Tool | Purpose | | --- | --- | | `pathrule_read_rule` | Returns the full body of a rule by id. | | `pathrule_write_rule` | Creates a rule at a node path with a scope type (`folder`, `file_type`, `project`) and a priority (`high`, `medium`, `low`). | | `pathrule_update_rule` | Edits an existing rule with optimistic concurrency. | | `pathrule_delete_rule` | Soft deletes a rule. Recoverable for thirty days. | Rules are workspace level and can be attached to multiple nodes through a join. Writing a rule at the same path twice should use update, not write, to avoid duplicates. ## Skill | Tool | Purpose | | --- | --- | | `pathrule_read_skill` | Returns the full SKILL.md body of a skill by id. For `github_ref` skills it returns the cached snapshot. | | `pathrule_write_skill` | Creates a skill at a node path. Accepts the full SKILL.md including frontmatter. Source can be `manual`, `template`, or `github_ref`. | | `pathrule_update_skill` | Edits an existing skill with optimistic concurrency. | | `pathrule_delete_skill` | Soft deletes a skill. Recoverable for thirty days. | For the authoring flow, see [Writing skills](/docs/content/skills). An assistant drafts first and calls `pathrule_write_skill` after the user approves the body. ## Patterns | Tool | Purpose | | --- | --- | | `pathrule_import_pattern` | Previews and imports a published bundle of memories, rules and skills at the chosen workspace path. | | `pathrule_remove_pattern` | Removes the pieces owned by a previously imported pattern bundle. | ## Activity | Tool | Purpose | | --- | --- | | `pathrule_log_activity` | Logs a structured record of a file modifying response. Required after every response that creates, edits, or deletes files. Fields: domain, action, scope, subjects, files_touched, task_summary. | The activity log feeds Studio's workspace activity and the derived learning layers. Logging one record per response (not per file) is the right granularity. ## Suggestions and refresh | Tool | Purpose | | --- | --- | | `pathrule_list_pending_refreshes` | Lists stale memory and rule items the self-audit has flagged. | | `pathrule_get_refresh_brief` | Claims a refresh task and returns the full repair context, including the audit reason and the assistant instructions. | | `pathrule_resolve_refresh` | Marks a refresh task applied or rejected. Closes the human in loop workflow. | | `pathrule_request_refresh` | Flags a memory or rule that the assistant found stale, contradictory, duplicated, too narrow or unclear during normal work. | Suggestions are how Pathrule keeps the content tree from drifting. The assistant can flag a concrete issue, claim a brief, propose a fix, and resolve it, all without leaving the editor. ## Local lazy-write control The local stdio server keeps read tools and `pathrule_log_activity` visible on startup. Write and admin tools are deferred in the default lazy mode so a read-only turn carries a smaller tool list. | Tool | Purpose | | --- | --- | | `pathrule_enable_writes` | Enables write, update, delete, pattern, setup and refresh-mutation tools for the rest of the MCP session. The server then emits `tools/list_changed`. | `PATHRULE_MCP_TOOLS=all` registers the full local set up front. Lazy mode removes nothing; it changes when mutation tools become visible. ## Hosted Remote MCP additions Remote MCP exposes the shared cloud-safe content and activity tools over OAuth, then adds hosted account operations: | Tool | Purpose | | --- | --- | | `pathrule_list_organizations` | Lists organizations visible to the signed-in user. | | `pathrule_list_workspaces` | Lists workspaces available through the approved OAuth scope. | | `pathrule_create_workspace` | Creates a hosted workspace before a local checkout exists. | | `pathrule_take_snapshot` | Captures a workspace knowledge snapshot. | | `pathrule_list_snapshots` | Lists snapshots available to the workspace. | | `pathrule_read_snapshot` | Reads one snapshot. | | `pathrule_get_local_runtime_upgrade` | Returns the supported path from a cloud connector to Studio or CLI when local delivery is needed. | Remote MCP also exposes setup, per-item reads and writes, patterns, refreshes and activity through the same shared names and shapes. It does not expose local batch helpers whose job depends on the stdio runtime's local workflow. ## Tools that only exist inside a Studio session Studio starts with the local Context Layer set above and can expose a second group to a session it started itself. | Group | Purpose | | --- | --- | | Design | Read the workspace's designs as intent (`design_index`, `design_screen`) and compare a rendered result against one (`design_fidelity`). See [verifying a design](/docs/design/verify). | | Run | Start the app target you selected in Studio, so the agent can bring a dev server or a build up itself instead of asking you to. | | Simulator | Drive an iOS or Android simulator and read its accessibility tree, which is how a native screen gets observed. | | Tasks | Read and move cards on the [Tasks board](/docs/studio/tasks). | Two properties are worth knowing: - **They register only when Studio is on the other end.** Each group appears only if Studio handed the process a run-bridge URL and token. Without those, `tools/list` does not return them, so your editor's own Pathrule MCP connection never has them. - **They are a typed bridge, not a shell.** There is no free-form command argument. A run tool names a target from a catalog Studio built; a simulator tool names a device and an action. ## Conventions A few conventions hold across the surface. - **Path first writes.** Write tools take a workspace relative `node_path` like `/apps/api` or `/`. If the path does not exist, intermediate nodes auto create. - **Optimistic concurrency.** Update tools require an `expected_version_id`. A mismatch returns a clear conflict response rather than overwriting. - **Compact by default.** Responses are compact for the common case. Pass `verbose: true` when you need the full record back. - **Stable ids.** Tool responses carry stable `id` and `version_id` values. The assistant can reference them in follow up calls without re reading the parent. ## What to read next - [MCP overview](/docs/mcp/overview) for the model behind the tool surface. - [How hooks work](/docs/hooks/how-hooks-work) for the push layer that complements these pull calls. - [Writing memories](/docs/content/memories), [Writing rules](/docs/content/rules), [Writing skills](/docs/content/skills) for what to put inside the writes. ## /docs/hooks/how-hooks-work # How hooks work The hook supervisor is the part of Pathrule that makes AI sessions feel like the assistant already knew about your team's conventions. It runs locally, reads from a cache, and delivers the right slice of memories, rules, and skills before the assistant takes its first action. This page is a user facing model of the mechanics. It is not a deep dive into the runtime internals. ## What is a hook A hook is a small script your AI client invokes at well defined moments in a turn. Pathrule uses the delivery and enforcement events each client actually exposes. - `UserPromptSubmit` scopes an upcoming turn on clients whose prompt event accepts context. - `SessionStart` supplies a one-shot bootstrap on clients whose prompt event cannot carry context. - `PreToolUse` supplies context or a strict-rule decision before an action when the client accepts it. - `PostToolUse` records outcomes and compensates with path-scoped context on clients whose pre-tool event accepts decisions but not context. When you attach a workspace, Studio handles the agents it runs natively. Pathrule CLI registers hook profiles for Cursor and GitHub Copilot, and can wire standalone Claude Code and Codex. Windsurf has no equivalent Pathrule hook profile, so its generated companion file supplies the session bootstrap and MCP supplies deeper context on demand. ## Client delivery profiles | Client | Bootstrap and context | Strict pre-write blocking | | --- | --- | --- | | Studio agents | Native Studio delivery | Yes | | Claude Code and standalone Codex | Prompt and pre-tool hooks | Yes | | Cursor and GitHub Copilot | Session start, post-tool context and pre-tool decisions | Yes | | Windsurf | Companion file at session start, then MCP | No Pathrule hook event | | Remote MCP | Explicit hosted MCP calls | No local hook runtime | ## What the hook does The hook supervisor does four things in order. 1. **Resolve the path**. It maps the working directory to a workspace node. 2. **Read the cache**. The local cache holds a precomputed index of memories, rules, and skills for that path. 3. **Shape the slice**. It picks a depth that fits the intent. A UI tweak gets a minimal payload. A bug fix or refactor gets a focused one. Discovery prompts unlock a deeper one. 4. **Return the payload**. The text comes back to the client as system context for the upcoming action. The whole flow is local. There is no network round trip in the hot path. ## What you see The assistant's context surface (the one your editor exposes) gains a Pathrule section. It lists: - The path the hook resolved to, plus the paths the work is most likely in, a route the assistant is asked to open before it searches. Pathrule records whether it did, so the routing is measured rather than assumed. - The matching rules with their priority. - The memories and skills most relevant to your prompt, delivered as full bodies the assistant can act on directly. Less certain matches still come through as titles with ids you can read in full if you want. - The skills attached to this scope. If the hook had nothing relevant for the current path, it returns a small empty marker so the assistant knows Pathrule was consulted and chose silence. ## When the hook is not enough Hooks are designed for the common case. The assistant can always reach for the MCP tools when it needs more. - For discovery prompts ("list everything we know about billing"), the assistant calls `pathrule_get_context` directly. - For full memory bodies, the assistant calls `pathrule_read_memory` with the id surfaced in the hook. - For writes (the user asks to save a convention or a rule), the assistant uses the corresponding write tool. The hook is the fast path. MCP is the deep path. Both share the same source of truth. ## Path scope keeps it small The hook returns a slice that is shaped by the working directory. - A change in `apps/web/dashboard` does not pull in rules about database migrations. - A change in `services/billing/webhooks` pulls in the billing rules and the webhook replay skill, not the marketing site conventions. - A discovery prompt at the repo root pulls in a workspace overview, not every body. Path scope is the main reason teams report large drops in context tokens after moving from a global CLAUDE.md style file to Pathrule. ## When nothing appears If you open a session and the Pathrule section is empty, run the doctor. ```bash pathrule doctor ``` It checks: - The workspace attachment for the current directory. - The local cache freshness. - The MCP server status. - The hook registration in your AI client config. The output reports any step that needs attention with a one line fix suggestion. ## What to read next - [MCP overview](/docs/mcp/overview) for the tool surface that backs the deep path. - [Core concepts](/docs/start/core-concepts) for the data model the hook reads from. - [CLI install](/docs/cli/install) for installing the runtime that hosts the hook supervisor. ## /docs/hooks/rules-as-guardrails # Rules as guardrails A rule in Pathrule is not a note the assistant reads later. It is a guardrail that arrives before the assistant acts. Most documentation tells you what went wrong after it shipped. A guardrail can stop the change before it lands. This page explains the difference between context that informs a turn and a rule that can block one. For the mechanics of how hooks deliver context, read [How hooks work](/docs/hooks/how-hooks-work) first. This page is about what a high-priority rule does once that context is in place. ## Pull asks. Push arrives. The old model is pull. The assistant has to remember to ask for your conventions, call a tool, and read the result before it edits anything. If it forgets, it edits blind, and you find the problem in review. The hook model is push. Context arrives at two moments without the assistant asking for it: when you submit a prompt, and right before the assistant uses a tool. By the time the assistant is about to write a file, the rules attached to that path are already in front of it. The assistant does not have to remember Pathrule exists for Pathrule to do its job. ## Two levels: advisory and blocking Not every rule should interrupt the assistant. Pathrule treats rules at two levels. - **Advisory rules** ride along as context. They appear next to the file the assistant is about to touch, with their priority, so the assistant can factor them in. They do not stop anything. - **High-priority rules marked for enforcement** can block. When the assistant is about to make a change that violates one, the hook stops the tool call before the file is written and returns the rule text as the reason. The assistant reads the reason and tries again, this time inside the constraint. The non-compliant version never reaches disk. The split is deliberate. Blocking a low-stakes edit wastes the assistant's turn and yours. Blocking is reserved for the rules where a violation is a real regression. ## Before and after Consider a rule that says secrets never go into committed files, marked high priority for enforcement. | | Without the guardrail | With the guardrail | | --- | --- | --- | | The assistant's intent | Add an API key to a config file to make a feature work | Same | | What happens | The edit lands | The hook blocks the tool call before the file is written | | When you find out | Later, in review (or not at all) | Never. The assistant sees the rule text and switches to an environment variable | | Result on disk | A committed secret | Nothing non-compliant was written | The same pattern applies to any rule a team has paid for in production: a data-access policy that must filter by user, a migration convention, a file that is generated and must not be hand-edited. The rule stops being a comment someone hopes the assistant read and becomes a wall it cannot walk through. ## Filenames pull the right memory You do not always have to wait for a tool call. When your prompt names a file that an attached memory is about, the hook can surface that memory's body at prompt time, before the assistant opens anything. Naming the file you are working on is often enough to put the right context in front of the assistant on the first turn. When more than one memory matches the same filename, the hook shows the candidates instead of guessing. ## Fail open by design A guardrail that breaks your workflow when it breaks is worse than no guardrail. Pathrule fails open. If the supervisor cannot evaluate a rule, errors, or times out, it does not block your work. The change proceeds. Enforcement is a safety net, not a gate you can get stuck behind. You stay in control. If you ever want hooks off entirely, one file turns them off. ## Verify it yourself You do not have to take the behavior on faith. To see which hooks your AI client has registered, read its settings file. For Claude Code: ```bash cat ~/.claude/settings.json ``` To turn every Pathrule hook off instantly (the kill switch), create one file: ```bash touch ~/.pathrule/kill-hooks ``` The next tool call passes straight through with no Pathrule involvement. Remove the file to turn hooks back on: ```bash rm ~/.pathrule/kill-hooks ``` To confirm a rule is actually attached to a path, open the assistant's Pathrule context surface in your editor. A high-priority rule shows up with its priority before the assistant acts on that path. ## What to read next - [How hooks work](/docs/hooks/how-hooks-work) for the delivery mechanics and the empty-state behavior. - [Writing rules](/docs/content/rules) for how to author a rule and mark it for enforcement. - [MCP overview](/docs/mcp/overview) for the deep path the assistant uses when the hook is not enough. ## /docs/hooks/work-safety # Work safety The same hook that puts the right memories and rules in front of the assistant can also stop a bad write before it happens. Most tools tell you about a collision after you push and review. Pathrule checks for it before the file is written, while the assistant is still in the turn. This page is about that check. For the mechanics of how hooks deliver context, read [How hooks work](/docs/hooks/how-hooks-work). For the related but different guardrail that blocks a non-compliant change, read [Rules as guardrails](/docs/hooks/rules-as-guardrails). This page covers the safety net that watches for risky edits to shared work. ## A clean write does not ask. A risky one does. Before the assistant writes a file, the hook runs a quick pre-tool check. If the file is clean, the check is silent and the write proceeds with no prompt. You see nothing. A write is treated as risky in two cases: - A teammate is actively working on the same file right now. - A teammate has changed that file locally and has not committed it yet. In either case the write surfaces as your AI client's normal confirmation moment, the same prompt you already see when an assistant asks before acting. There is no Pathrule modal, toast, or dashboard detour. The message names the person and the conflict, and nothing else: ```text Pathrule caught a possible conflict. Ahmet is actively working on this file. Continue? ``` ```text Pathrule caught a possible conflict. Ahmet changed this file 3 days ago and has not committed it yet. Continue? ``` It does not mention setup, settings, health checks, or how the conflict was detected. It tells you who and what, then lets you decide. ## Two different guardrails It is worth separating this from rule enforcement, because they behave differently on purpose. | | Work-safety check | High-priority rule | | --- | --- | --- | | What it watches | Whether the file is being touched by a teammate or has their uncommitted changes | Whether the change violates a rule you marked for enforcement | | What it does | Asks before the write, then lets you continue | Can block the write outright before the file is written | | Why | Pathrule cannot prove intent across tools well enough to deny, so it warns | A violation here is a real regression you chose to wall off | | You see | Your client's normal confirmation prompt | The rule text as the reason, so the assistant can retry inside the constraint | The work-safety check asks. It does not hard-lock the file. A determined write can continue, because warning the human is the safer default when the system cannot be certain. The blocking behavior of an enforced rule is covered in [Rules as guardrails](/docs/hooks/rules-as-guardrails). ## Active work and uncommitted work expire differently The two risky cases age out on their own terms. - **Active work** is short-lived. Once a teammate stops touching the file, the active warning expires by itself. - **Uncommitted work** is durable. If a teammate changed a file and walked away, the warning keeps appearing days later until that change is committed, reverted, or stashed. It clears on the next scan after the change is resolved, not on a timer. This matters: the most common way one person silently overwrites another's work is editing a file the other person changed last week and never committed. That case does not expire, so it still asks. ## Your own work never warns you The check is about teammates, not you. Your own uncommitted changes do not trigger a warning, so on a personal workspace it stays quiet almost all the time. You only see a prompt when the file is in someone else's hands. ## It fails open A safety check that breaks your workflow when it breaks is worse than no check. This one fails open. - If the check cannot verify in time, a write asks with a short degraded message and a read is allowed straight through. It never hangs the assistant waiting on a verdict. - A degraded prompt is honest about what it could not do: ```text Pathrule could not verify teammate local state in time. Continue? ``` - One file turns every Pathrule hook off instantly, the same kill switch described in [Rules as guardrails](/docs/hooks/rules-as-guardrails). The check is a net under the work, not a gate in front of it. ## Nothing leaves the machine that should not The check works on path-level metadata about who is touching what file, not on the files themselves. Source code and diffs are never stored remotely. There is no setup, wizard, opt-in, or panel to monitor: if you have a normal Pathrule runtime installed, the check is already on, and it stays invisible until there is a real conflict. ## It works the same across surfaces A teammate on Pathrule Studio or on the CLI publishes the same work state, and all see the same confirmation for the same conflict. Mixed teams are first-class: one person on Studio and another on the CLI get matching behavior. Pathrule Web is the cloud management console and does not run local hooks, so it cannot inspect local files and does not participate in this check. ## Verify it yourself You do not have to take the behavior on faith. To turn every Pathrule hook off instantly, including this check, create one file: ```bash touch ~/.pathrule/kill-hooks ``` Remove it to turn hooks back on: ```bash rm ~/.pathrule/kill-hooks ``` If you ever need to reset your own published work state, the CLI reconciles it from a fresh scan: ```bash pathrule work-state reconcile ``` ## What to read next - [Rules as guardrails](/docs/hooks/rules-as-guardrails) for the guardrail that blocks a non-compliant change outright. - [How hooks work](/docs/hooks/how-hooks-work) for the delivery mechanics behind the check. - [Writing rules](/docs/content/rules) for marking a rule high priority for enforcement. - [MCP overview](/docs/mcp/overview) for the tool surface the assistant uses when it needs more. ## /docs/retrieval/how-retrieval-works # How retrieval finds the right knowledge A workspace can hold thousands of memories, rules and skills. The job of retrieval is to put the few that matter into the assistant's context before it starts, and to leave the rest out. This page describes how that selection works and how it improves over time. It does not cover the scoring math, which is intentionally not published. ## Path scope comes first The first filter is location. Every memory, rule and skill lives at a node path. When the assistant works in `/apps/api/payments`, Pathrule starts from what is pinned to that path and what it inherits from the paths above it. A UI tweak in `/apps/web/dashboard` does not pull in the rules about database migrations. This is the same path scope described in [Core concepts](/docs/start/core-concepts), applied as the first cut. By the time anything more expensive runs, the candidate set is already small. ## Meaning and keywords, together Once the path narrows the field, Pathrule matches your intent against the candidates two ways at once. - **Keyword matching** catches exact hits: a file name, a function name, a literal phrase from a memory title. - **Meaning-based matching** catches the rest: a question phrased differently from how the memory was written, a synonym, a paraphrase, a concept that shares no words with the entry. The second one is not a text search with extra steps. Every entry is also held as a computed representation of what it means, your request is turned into the same kind of representation, and the two are compared directly. That is why a match can happen with no shared string at all, and it is the first of several things the layer computes rather than stores. See [what Pathrule computes](/docs/start/what-pathrule-computes). Neither alone is enough. Keyword search misses a memory that says the same thing in other words. Meaning-based search can blur an exact file-name match. Pathrule runs both and combines them, so an exact match keeps its priority and a same-idea-different-words match still surfaces. ## The files next to the one you are in Path scope and meaning both start from where the assistant is working. A third signal widens that slightly: Pathrule learns which files your team habitually changes in the same piece of work, and lets knowledge attached to those neighbours surface too. It means a decision recorded once, on the file where it was made, still reaches the sessions that need it, even when the prompt never mentions that file. The signal is built only from the activity your agents log, never from reading your code, and it fades as those relationships stop happening. See [files that change together](/docs/retrieval/co-change). ## It works across languages The meaning-based match is not tied to one language. A prompt in Turkish can surface a memory written in English, and a mixed-language prompt still finds the right entry. This is the case plain keyword search cannot handle. When the prompt and the memory share an idea but no words, matching has to work on meaning rather than spelling. ## The best matches arrive ready to use Retrieval delivers in two tiers. The entries that clearly fit the prompt come through as full content, so the assistant works straight from your team's knowledge instead of going to read it. Only the most relevant few are sent each turn, and content the assistant already has is not sent again, so the assistant gets what it needs without carrying the whole knowledge base. ## Candidates are evidence, not answers When retrieval is not certain, it does not pretend to be. Pathrule surfaces likely entries as candidates and tells the assistant to read the full body before acting on one. A candidate is a pointer worth checking, not a fact to repeat. This follows Pathrule's standing rule that wrong context is worse than no context. In an ambiguous case Pathrule shows a candidate rather than asserting an answer. ## It learns from how knowledge is actually used Retrieval is not frozen at the moment a memory is written. Over time Pathrule observes which entries actually helped on which kinds of work, and lets that move future results. An entry that keeps proving useful for a kind of task is more likely to surface for similar work later. The observation is concrete rather than a rating anyone gives. Each delivery opens a record of what was sent, and the turn reports back into it: which of those entries the assistant actually consulted rather than merely received, how many tool calls the work took, how many failed and on which files. A turn that received knowledge and still ran into failures counts against the knowledge it was given, weighted by how bad the failure was. That record is taken by the layer that did the delivering, not asked for. The assistant does not have to call a tool, remember a session id or cooperate in any way for the turn to be measured, which is what keeps the loop honest across every client, including the ones that would never volunteer anything. Because the record is kept per kind of work, the result is not one score per entry. The same memory can rank high for a migration and low for a UI tweak. A single importance field, maintained by hand, cannot express that difference. The learning is conservative by design. - **Ambiguous signals are skipped, not recorded.** A sarcastic reply or an unclear outcome does not teach the wrong lesson. - **A clear miss reduces, it does not erase.** A single clear miss lowers an entry's standing for that kind of work rather than wiping out its history. - **Influence fades with time.** An entry that stops matching the current code naturally loses ground instead of haunting results forever. And it changes the choice, not the size. What an entry has proven can move it ahead of an equally relevant rival, but it cannot push an entry past the relevance bar that decides whether anything is sent at all. A workspace that has been learning for six months delivers a better few entries per turn than it did on day one, in the same amount of context. Learning here buys accuracy, not room. Ranking happens in two layers. The base ranking that decides which candidates surface is open source and runs locally, so you can read how it chooses. The learning layer that re-ranks by real usage is the part the cloud edition adds on top. [How knowledge compounds](/docs/start/how-knowledge-compounds) covers this loop end to end, and [Suggestions and self-audit](/docs/content/suggestions) covers how stale entries are raised for review. ## Computed once, the same for the whole team The selection runs on the server, not in each person's client. Two teammates asking the same thing on the same path get the same result, and the answer does not drift across Claude Code, Codex, Grok, Kimi, Antigravity and OpenCode in Studio. Cursor, Windsurf and GitHub Copilot receive the same selection when connected through Pathrule CLI. It also means the learning is shared. When an entry proves useful, it surfaces better for everyone on the team, not just the person who triggered it. Claude should not be smarter for one person than for the team. ## What retrieval never sees Retrieval operates on your team-written memories, rules and skills, plus the path you are working in and the words of your request. It does not read, scan or upload your source code. The match runs over knowledge your team chose to write down, not over the repo itself. ## Where this fits - [Core concepts](/docs/start/core-concepts) defines path scope, the first filter retrieval uses. - [How hooks work](/docs/hooks/how-hooks-work) describes how the selected slice reaches the assistant before its first tool call. - [How knowledge compounds](/docs/start/how-knowledge-compounds) places retrieval inside the deliver, capture, score loop. ## /docs/retrieval/graduated-delivery # What arrives in full, and what arrives as a name Retrieval has two jobs. Choosing the right knowledge is the famous one. Deciding how much room each chosen entry deserves is the one that determines whether the good answer actually fits. Pathrule used to answer the second question with one word: everything that ranked went out as full content, in rank order, until the room ran out. The entry ranked eighth got exactly the treatment the entry ranked first got, and the entry ranked ninth got nothing at all, even when it was relevant. Relevance decided the order and nothing else. Now relevance decides the form. ## Three forms, one ranking - **The closest few arrive as full content.** The assistant reads them and acts, with no separate fetch and no round trip. - **Everything else relevant arrives as a name, an id and one line.** Around sixty characters. Enough for the assistant to recognise it and pull the body when it turns out to matter. - **Skills arrive by name only**, however well they rank. More on that below. The important property is the one at the bottom of the list: nothing relevant is thrown away for want of room. Discarding a correct answer because it landed in an inconvenient position is the one outcome that was never acceptable, and the cheap form is what makes it avoidable. The default keeps the top three bodies, and that number came from measurement rather than taste. Keeping only two would have saved about a tenth of the context by giving up the third-best body on every single prompt. Keeping three preserved it and still cost less than the old behaviour of sending every ranked entry whole. Correctness set the default; the cheaper setting stayed available for anyone who wants it. ## Why a skill is never pushed A memory is a fact. A rule is a constraint. Both are things an assistant should simply know while it works, so both can arrive as content. A skill is a procedure. Putting a procedure into the context of a turn that did not ask for one does not inform the assistant, it instructs it, and an assistant that has been handed a checklist tends to follow the checklist. So skills are offered by name and the assistant reaches for one when the work is actually the work that skill describes. See [writing skills](/docs/content/skills) for what a skill is meant to be. ## Rules earn their room too Rules used to bypass the relevance test on the way in. The effect was measurable and it was not subtle: on a run of real prompts, rules were taking the overwhelming majority of the available room while most of those prompts delivered no memories at all. A constraint about database migrations was crowding out the memory that would have answered a question about a button. Rules now pass through the same relevance test as everything else. The exception is deliberate: a rule marked strict keeps its body unconditionally, because a hard constraint whose violation causes a regression is not something to ration. ## The demotion is what makes relevance observable There is a second reason the cheap form matters, and it is about learning rather than cost. When every ranked entry was pushed as a body, the layer never found out whether any of them were wanted. A body that arrives unasked produces no evidence either way. An offered name is different: the assistant either pulls it or does not, and a pull is a deliberate act by the party that knows what the work needed. That pull is the first honest relevance label this system can collect, and the payout for a pulled name is a body slot next time rather than a nudge in a ranking nobody can see. It fits the wider loop described in [how retrieval finds the right knowledge](/docs/retrieval/how-retrieval-works): the layer measures what it delivered rather than asking the assistant to report back. ## The bar has to hold in every language The relevance bar is a single threshold, and it turned out to be quietly language dependent. The same memory scores one way against a prompt written in English and lower against a faithful translation of that prompt, because meaning-based matching does not produce identical numbers across languages for the same idea. A bar tuned against English prompts therefore cuts off the other languages without anyone noticing, and the symptom is not an error. It is a team that writes its prompts in Turkish getting less context than a team that writes the same prompts in English. So the bar is set where it holds for all of them, and the behaviour is verified rather than assumed. Across seven languages, the memory that should have won ranked first in every one of the thirty five case and language pairs tested, and a precisely worded prompt found its entry every time in all seven. ## A prompt that asks two things gets knowledge for both Ask one question and meaning-based matching works well. Ask two in the same message and it has a structural problem: the request becomes a single average of two different ideas, and an average of two things is often close to neither. The entry that answers your first question and the entry that answers your second can both fall short of a bar that either would have cleared on its own. Pathrule now reads a multi-part request as its parts. Each clause is matched separately, the clauses are matched at the same time rather than one after another, and the results are merged by best match per entry. Two-part questions went from finding knowledge for roughly two thirds of the parts to finding it for all of them in one language and nearly all in another, while single-part questions were unaffected and the time it takes did not move, because the clauses are matched concurrently. The room available grows with the question rather than with the workspace. Asking two things costs a little more than asking one. Having ten thousand memories instead of a hundred costs the same. ## What to read next - [How retrieval finds the right knowledge](/docs/retrieval/how-retrieval-works) for the selection this delivery model sits on top of. - [How hooks work](/docs/hooks/how-hooks-work) for how the selected slice reaches the assistant before its first tool call. - [How Pathrule proves hard claims](/docs/start/technical-proof) for the contracts behind the relevance bar and the recorded outcomes when nothing is delivered. ## /docs/retrieval/co-change # Files that change together Some files travel in pairs. A route and its validator. A migration and the type that mirrors it. A component and the token file it reads. Nobody writes that down, and it is rarely visible in the folder structure, but everyone on the team knows it after a few months. Pathrule learns it from the work itself. When your agents log what they did, each entry carries the paths it touched. If two paths keep appearing in the same piece of work, Pathrule records that they change together and gives that relationship a weight. ## What it does for retrieval Path scope and meaning-based matching both start from where you are. Co-change adds the files next to it. When the assistant is working in `/apps/api/payments/refund.ts`, retrieval already considers what is pinned to that path and what matches the intent. Co-change lets knowledge attached to the paths that habitually move with it rise as well. So a rule about the ledger writer can reach a session that never mentioned the ledger, because in this codebase refunds and the ledger have always been edited together. This matters most for the knowledge nobody thought to attach in two places. A decision recorded once, on the file where it was made, still reaches the sessions that need it. ## How the relationship is measured A pair counts when both paths appear in the **same logged piece of work**. Sharing a folder is not enough, and neither is being changed on the same day by different tasks. The unit is one piece of work, because that is what indicates a real dependency rather than a coincidence of layout. Weights are rebuilt from a rolling window of recent activity. On every rebuild, existing weights decay and fresh observations are added, then pairs that fall below a noise floor are dropped. The effect is that a relationship which stops happening stops mattering, without anyone having to remove it. A refactor that splits two files apart shows up as their weight fading over the following weeks. ## What it is built from, and what it is not The signal is built **only** from the activity your agents log. Pathrule does not read your source code, your diffs or your commit messages to compute it, and only the file paths from those log entries are used. That has a practical consequence worth knowing: it needs a real editing history. A workspace where every logged task touches exactly one file produces no pairs at all, because there is nothing to pair. In that case retrieval keeps working from path scope and meaning, and co-change contributes nothing rather than guessing. It is also per workspace. Relationships learned in one workspace never leak into another, and the whole signal sits behind the same access control as the rest of your knowledge. ## Where to look Co-change works in the background, so there is nothing to configure and nothing to switch on. It becomes more useful as your team logs more work, which is the same thing that makes [work episodes](/docs/content/work-episodes) and [suggestions](/docs/content/suggestions) more useful. If your agents are logging their work, this is already accumulating. ## /docs/retrieval/friction # Files that slow an assistant down Some files are harder for an assistant to work in than others, and the reason is usually not the code itself. A path in your docs that moved. A generated file that cannot be edited safely. A directory that needs a permission the agent does not have. You already know which files those are, roughly, from having been annoyed by them. Pathrule records it precisely. ## What gets recorded When a tool an assistant calls fails, three things are stored: the kind of tool, the file it was working on, and a short code for how it failed. `file_not_found`, `permission_denied`, `timeout`, `rate_limit`, `token_limit`, `syntax_error`, or `unknown` when the failure is real but nothing recognises it. That is the whole record. Not the command. Not the error message. Not the file. A count and a code, attached to a path. The failure is observed, not reported. Pathrule watches the tool call itself, so the count does not depend on the assistant noticing its own mistake, remembering a session, or calling anything afterwards. An assistant that fails quietly and moves on is recorded exactly like one that announces it. How long the call took is part of the same observation, which is what lets a command that hung be told apart from one that refused. The path is normalised to workspace-relative form first, which matters more than it sounds. An absolute path on a laptop is `/Users//…`, and that name has no business travelling to shared knowledge. Relative paths also mean the same file groups correctly across a team, instead of once per machine. ## What it is used for **A weekly picture.** Failures group by week, file, tool and code. What comes out is a short list rather than a chart: the files an assistant fails in most, and how. A file that keeps appearing under `file_not_found` is usually a stale path somewhere in your own instructions. One under `syntax_error` is usually a file that is genuinely awkward to edit. One under `permission_denied` is usually a setup problem you can fix once. **Retrieval learning.** If a turn received knowledge from Pathrule and still ran into failures, that knowledge takes a small negative signal. Permission, token-limit and rate-limit failures weigh more than an ordinary miss, because those tend to mean the guidance sent the assistant somewhere it could not go. The signal joins the loop described in [what makes knowledge rank higher](/docs/retrieval/how-retrieval-works). Knowledge that keeps showing up in turns that go badly gradually stops being chosen, without anyone having to review it. ## What the signal cannot see This part depends on which assistant you use, and it is not uniform. File tools report failures properly. A read, edit or write that fails arrives with its message, gets classified, and lands on the right file. That is the case that matters, because a file path is what makes a count actionable. Shell commands often do not. Some assistants report no exit code at all, so a command that fails and one that succeeds arrive looking identical. Pathrule does not infer a failure from output text: a search result can legitimately contain the words "no such file or directory", and a wrong failure attached to a file is worse than a missing one. When the assistant does not report a failure, nothing is recorded, and when it reports one that no rule recognises, the code is `unknown` rather than a guess. ## What it never does It never blocks a tool call, never slows one down, and never appears in the assistant's context. A failure is a fact about your codebase, recorded after the fact. It does not change what the assistant is allowed to do, and a file with a bad record is not treated as off limits. Nothing here is a score attached to a person: the record is about files, not about who was working in them. ## /docs/cli/install # Install Pathrule CLI is the terminal first surface for Pathrule. It runs the local MCP server, the hook supervisor, and the local cache for agents you drive from a shell. This page shows how to install it and sign in. ## Requirements - macOS, Linux, or Windows. - Node.js 20.11.1 or newer (npm is the install path on every operating system). - A modern shell: zsh, bash or fish, or PowerShell on Windows. - An AI coding assistant that speaks MCP. Pathrule CLI is the supported integration route for Cursor, Windsurf and GitHub Copilot, and it can also wire standalone Claude Code and Codex CLI. Optional for install, but you will want one to verify the hook flow. ## Install ### npm (macOS, Linux, Windows) `npm` is the install path on all three operating systems. It needs Node.js 20.11.1 or newer. ```bash npm install -g @pathrule/cli ``` On Windows, run this from PowerShell. Pathrule registers a Windows compatible hook command automatically, so the same `pathrule` commands work there exactly as they do in a Unix shell. ### Direct download If you prefer not to use a package manager, see [the CLI page](/products/cli) for the latest signed release, extract it, and put the `pathrule` launcher on your PATH. It runs on macOS, Linux, and Windows and needs Node.js available. A Homebrew tap for macOS is planned. Until it is live, use npm. ### Verify ```bash pathrule --version ``` The CLI prints its version and exits zero. If the command is not found, make sure the install location is on your PATH and reopen the shell. ## Sign in Two flows. Pick the one that matches the machine you are on. ### Browser PKCE flow Use this on a desktop or any machine with a browser available. ```bash pathrule login ``` The CLI opens a browser, you sign in to your Pathrule account, and the CLI receives a session over the PKCE callback. No tokens are pasted into the terminal. ### Device code flow Use this on a headless box, an SSH host, or a CI runner. ```bash pathrule login --device-code ``` The CLI prints a short verification URL and a code. Open the URL on a machine with a browser, enter the code, and approve the session. The CLI completes the handshake without ever holding your password. ## Attach a workspace A workspace is the unit Pathrule scopes content to. Attach it to the local directory you want it to apply under. ```bash pathrule workspace list pathrule workspace attach --workspace my-team --path ~/repos/my-team ``` After attach, any time you run an AI client in a directory under that path, the runtime knows which workspace's content to serve. ## Verify the wiring The doctor is the single command that confirms everything is hooked up end to end. ```bash pathrule doctor ``` It checks: - The local cache exists and is fresh. - The MCP server starts and responds to a ping. - Each supported AI client config points at the right MCP command. - The hook registration is current for the AI clients you have installed. If anything is off, doctor prints a one line fix suggestion. Most issues are resolved by running `pathrule repair`, which re writes the configs to the expected state. ## What to read next - [Quickstart](/docs/start/quickstart) to write your first memory and watch the hook fire. - [How hooks work](/docs/hooks/how-hooks-work) for the model that explains what doctor is verifying. - [MCP overview](/docs/mcp/overview) for the tools the assistant calls once the runtime is up.