Files and ownership

Before you or your agent edit a file discerndiscern↗A tool that lets you hand real work to coding agents and still decide what joins your project. put in your project, this page tells you whether the edit will last: which files are yours, which ones discern maintains a part of, and which ones it rebuilds from a source you edit instead. It also lists every record discern keeps inside .git and in temporary files, how long each one lasts, and what uninstalling removes and keeps.

Say you want every agent working on your recipe app to run the tests before it commits, so you open AGENTS.md to add that rule. AGENTS.md is a generated fileGenerated file↗A file discern builds for your coding agents: an agent file or a skill folder.: the next discern refresh rebuilds it from the project's instruction sourceInstruction source↗The file where your project writes its own instructions for coding agents., and your line would disappear. The rule belongs in discern/instructions.md, which is yours, and the refresh compiles it into every agent fileAgent file↗An instruction file your coding agent reads when it works on your project..

Every file discern registers has one kind of ownership, which decides who may change it:

Project-owned filesProject-owned file↗A file that belongs to your project, even when discern created its first copy. have one exception: the index of Architecture Decision Records (ADRs), the records of why the project made its significant design decisions. Setup seeds _adr/README.md in the project's map with a region between BEGIN GENERATED and END GENERATED markers. discern refresh rewrites that region from the record files, and discern done fails when the region has drifted from them, so the index stays in step with the records. Everything outside the markers stays yours.

A provider-local file belongs to a coding tool, which creates and maintains it: Claude Code's machine-local permission settings, for example. discern only keeps its registered path out of Git, and other untracked files a coding tool creates have no entry.

Ownership here decides who may edit or overwrite a file, and nothing more. It doesn't assign copyright or change a file's license, which authorship decides.

Each Git repository has one discern installation, with one discern.toml at the repository root. In a monorepo, that one file can set different checks for different folders. A folder that is itself a separate Git repository can have its own installation.

A discern.toml in an ordinary nested folder isn't a second installation, though commands you run beneath that folder use it as their project root. There, discern doctor fails its repository-shape check, and discern start and discern accept refuse, because a worktreeWorktree↗A separate copy of your project, on its own branch, where one task's work happens., the separate copy of the project where one task happens, always checks out the repository from its root.

The discern-authored portions column in the inventory below gives the license of the material discern wrote into each file: the Apache-2.0 project-payload grant. Project, user, provider, and third-party portions of the same file keep their existing terms.

Each shared or generated file also has a provenance class, which decides whether it carries a marker saying where it came from:

• Context-loaded: no marker. Agents load agent files and skills in full, so a marker would take up space in every session's context, and coding tools render comments differently. Instructions and drift checks enforce ownership instead.
• Comment-incapable: no marker, because JSON doesn't allow comments.
• Comment-capable non-context: the marker names the file's source, as the second line of the .gitignore block below does. In a shared fileShared file↗A file where discern maintains some parts and your project owns the rest., it names only the part discern maintains, such as "This block". By default the marker also names discern and links to discern.sh. A non-empty DISCERN_NO_ATTRIBUTION keeps the source and removes the product name and link.

A missing marker doesn't make a file project-owned, so look the file up in the inventory below before you edit it.

In this table, /** covers a directory. Provider-local files are listed too, so you don't mistake an ignored file for a generated one.

The table shows the paths of a fresh install. The .env and .env.local rows are the default [worktree].env_files. A project that sets its own list uses those files instead, with the same Shared and Apache-2.0 answers.

Configuring a different path moves a file, but its ownership still decides who may edit or overwrite it.

The agent files AGENTS.md, CLAUDE.md, and GEMINI.md are tracked, so an agent in a fresh clone, including a cloud agent, reads its instructions before discern has run. discern done blocks a stale copy, and accepts a missing one.

The tracked-refresh plan, the changes an ordinary discern refresh would make to tracked files, also covers discern's portions of other tracked files: the generated attributes, the exceptions in discern's .gitignore block, the provider integrations, and the ADR index. discern done and discern accept require that plan to be empty before a change lands, so the landed commit already holds their current versions. After landing, acceptance materializes only ignored or local files.

Materialized skills and provider-local files stay out of Git: discern done fails at its tracked_artifacts stageStage↗A group in the order the gate runs its work. if one of them has been force-added. Another tool's skills are never flagged.

discern maintains one marked block in .gitattributes, and your rules outside the markers stay unchanged, including nested and Git-local attribute files. setup, refresh, and upgrade rebuild the block from discern.toml, the source-path registry, and the active agents, so a rebuild replaces any hand edit inside it.

• Merge driver: the block requests merge=discern-generated for every tracked generated artifact you declare, and for the live agent files, so a plain git merge keeps the current side of those files instead of stopping on conflict markers, and the next regeneration rebuilds them from the merged sources. A [generated] pattern that .gitattributes can't express is left out, and refresh warns about it: whitespace, a leading !, #, or ", a backslash, a . or .. segment, an empty segment, braces, or an extended glob group. discern doctor flags the tracked paths such a pattern leaves unprotected.
• Checking protection: discern doctor passes the same set of paths to git check-attr --stdin -z merge, so Git itself decides each path's protection. Doctor reports unsafe values without rewriting your rules.
• GitHub's generated marking: set linguist_generated = true inside one [generated.<name>] table to mark only that group's paths as generated for GitHub, which then hides them in diffs by default and leaves them out of language statistics. The default is false.
• Markdown diffs: Markdown in each of discern's registered locations that exists uses Git's built-in markdown diff driver. That covers the configured map, instructions, skills, scripts, TODO, and brief paths, and the active agent files. There's no rule for every *.md file, so your README and other Markdown follow your own attributes.

discern ignores provider-local files by their exact registered paths, so neighboring files stay as they are. In the recipe app, which uses Claude Code and Codex, the block reads:

# --- discern ---
# This block managed by discern via the bundled .gitignore fragment and provider registry | https://discern.sh
# discern's managed ignore rules: machine-local provider state only.
# The skills discern materializes are ignored by an ignore file inside
# each provider skills directory that lists just those entries, so
# skills other tools install beside them stay visible to Git. discern
# owns this block alone and never touches your other rules. The agent
# files (AGENTS.md and its mirrors) are tracked, so every agent —
# cloud included — reads them from a fresh clone. For the full list
# of discern-managed files, run `discern docs` or see https://discern.sh
/.claude/settings.local.json
# --- /discern ---

You can add ignore rules for the agent files outside discern's block if you prefer, since the stale-copy check accepts a missing agent file.

discern owns only its marked block, plus any standalone rule outside it that exactly matches one the current provider registry declares. Similar broad or retired rules outside the block stay yours. When [worktree].root resolves inside the repository, the block also ignores that exact directory. The default worktree location, beside the project, needs no rule.

The Shared provider files above, such as .mcp.json, are tracked so a fresh clone loads discern's tools. When your own .gitignore excludes one, discern's block re-includes exactly that file. For a folder rule, the block re-includes the folder, ignores its contents again, then re-includes discern's files, so everything else the rule matched stays ignored. discern never edits your rules, and a line of yours that matches one of these exceptions stays yours. The block keeps its place unless a rule of yours after it excludes one of these files; it then moves to the end, because Git applies the last matching rule. discern refresh keeps these exceptions current, so adding a coding agent needs nothing more.

Setup leaves out of its commit an integration file that already held another tool's entries, since those can be personal settings or credentials, and names it for your agent. discern doctor warns under integration files when Git still ignores one of these files and doesn't track it.

Coding tools' configuration files, such as .mcp.json, .claude/settings.json, and .codex/config.toml, often hold entries from several tools. discern changes only its own entries there, in a form the other tools don't have to undo:

• JSON files keep their layout. discern writes its entry in the file's existing indentation, line endings, and final newline, so another tool that writes the same file sees only that entry change. Uninstalling removes the entry the same way. A new file, or an empty {}, gets two-space indentation.
• Markers claim only discern's part. In a shared file that allows comments, discern's marker names the entries it maintains instead of calling the file generated. .codex/config.toml, for example, opens with # MCP server, writable-root, and doc-size entries managed by discern via the Codex integration and discern.toml, so the tables other tools write there stay visibly theirs.

A coding agent's skills directory, such as .claude/skills/ or .agents/skills/, is shared with other tools. discern owns only the skills named in its .discern-materialized.json record there, and a .gitignore it writes beside them ignores exactly those. You can commit another tool's skills, so fresh clones and worktrees get them, and discern uninstall keeps them.

If an entry discern didn't place holds the name of one of its skills, or the directory already has your own .gitignore, discern refresh leaves it alone and reports a conflict with its fix. discern done then fails until you free the name: rename either side, or list the skill in [skills].exclude. discern doctor warns when an ignore rule hides another tool's skill.

To choose whether another tool's skills stay in these directories or reach every coding agent through discern, see Use discern alongside other agent tools.

discern writes only these Git configuration entries, all in the clone's own configuration:

The generated merge driver has one definition, in the shared clone configuration, which works from the main checkout and every linked worktree, and reconciliation moves redundant config.worktree copies into it. Git configuration doesn't travel with a clone, though: a fresh clone has the tracked attributes but not the driver, so its first setup or discern refresh installs it.

discern writes the Proof note fetch mapping and its marker only when [repository].proof_notes_mode is "fetch", so with the default, "local", your remotes get no discern configuration. An identical fetch mapping without discern's marker belongs to the project, and stays unchanged.

discern keeps these working records under discern/ inside Git's administrative directories, outside your commits. Don't edit them by hand: your agent works with them only through discern's commands, which keeps checks, approvals, and recovery state consistent across sessions.

The Lifetime column says where each record lives. A repository record lives in the common Git directory, where every worktree shares it. A worktree record belongs to one worktree, and disappears with it.

discern replaces a durable record through one interruption-safe writer, so an interrupted write leaves the old record intact. Intentional moves, and records written once, follow their own rules. Tests guard each record's namespaceNamespace↗The folder that holds your project's own discern content, discern/ by default., lifetime, and reset behavior.

• Parked tasks: discern worktree park copies the task's wording into discern/parked-tasks/ before it removes the worktree record. A successful discern start --from at the parked commit moves the wording into the new worktree and removes the record.
• Continuations: records behind discern await resume handles have a 7-day time limit and a 512-record repository cap.
• Removed worktree paths: each record has a 90-day limit, and the store has a 256-record cap. A record only lets discern offer an explicit prune of that recorded path.

When you drop a worktree, discern keeps its committed tip reachable through an ordinary ref under refs/discern/recovery/, so Git doesn't discard the dropped task's commits. Because it's an ordinary ref, Git keeps it in its files or reftable storage like any other. discern keeps the newest 32 refs, and they stay local unless you configure a transport for them. discern uninstall leaves them in place, because a ref may be the only remaining name for commits you wrote. When you no longer need that recovery history, review each ref and delete it with git update-ref -d <ref>.

An ordinary landing moves the trunkTrunk↗Your project's shared branch, usually main, where finished changes land., your project's shared branch, and creates its marker, refs/worktree/discern/acceptance-transactions/<transaction-id>, in the same ref transaction, so the marker exists only if the trunk moved. If a landing is interrupted, recovery reads that marker and the worktree's journal, and never replays the landing's authority:

• if the trunk already points at the landed commit, discern finishes the landing's cleanup;
• if the trunk was reset or moved somewhere else, recovery stops and asks you to inspect the trunk's reflog.

discern/release-check.json supports update reminders, and every linked worktree shares it. It records when the project first adopted discern, and the time and version of the last release handoff.

• A setup that finishes with honored Proof, or a successful discern upgrade, creates the record when it doesn't exist. Neither resets an existing record.
• Any discern releases run that isn't a dry run records a handoff, which resets the reminder clock. That includes runs with --json or --markdown, where no browser opens.
• A reminder can appear 14 UTC calendar days after the last handoff, or after first adoption. Viewing the reminder leaves it in place.
• discern never overwrites a record in a newer format, or one it can't read.
• Turning off the logbook doesn't affect the record, and discern uninstall removes it.

Uninstall never deletes a ref, because a ref can be the last name for commits or evidence you still need. Its result can suggest exact git update-ref -d '<ref>' commands for the private refs it kept, such as the Proof notes ref. Run one only once you've established you no longer need what it holds. Ordinary local branches stay visible as branches, and get no cleanup suggestion.

discern writes temporary files in the operating system's temporary directory, outside the project and its commits.

A file's name includes the project and worktree when discern knows them. Without a checkout identity, the name is the family prefix, a random part, and .log.

Registered temporary files expire after 24 hours, and discern prepare, discern done, and discern test sweep them. One sweep inspects at most 500 matching entries and removes at most 500 expired entries. The repository runs at most one page per hour, and keeps a cursor, so later pages work through a large backlog. discern sweeps only its registered families: files with a registered prefix and the .log suffix, and directories with a registered prefix, which it removes with their contents. It never touches other temporary files.

A crash report in the repository is <git-common-dir>/discern/crash/<timestamp>-<pid>-<unique>.txt, with mode 0600, and discern keeps the newest 20. A crash on the command line exits 70, and JSON output reports error: "internal_error". A crash inside a Model Context Protocol (MCP) tool returns an internal_error result, and the server keeps running. When the repository's crash directory isn't available, the report uses the crash fallback family above.

A report records the discern versiondiscern version↗The version of discern you're running, shown by discern --version., the timestamp, the command that ran, the platform, the runtime version, the error's name and message, and the stack. It's local diagnostic evidence, and it can contain local paths, so read it before you share it. For what to keep and what to clean up, see Crashes and local state.

discern uninstall removes discern from the repository. Preview it with discern uninstall --dry-run.

It removes:

• generated files;
• discern's entries in shared files;
• discern's blocks in .gitignore and .gitattributes;
• the whole discern/ runtime-state namespace inside Git's administrative directories;
• the shared generated-merge driver, and its obsolete checkout-specific copies;
• only the Proof note fetch mappings that carry discern's marker.

It keeps:

• project-owned files and discern.toml;
• Git configuration without discern's marker, and checkout-specific configuration the project still needs;
• every ref. It reports the private refs it kept, with optional exact cleanup commands, and runs none of them.

In the recipe app, uninstalling removes the generated AGENTS.md and CLAUDE.md and keeps discern/instructions.md, so your test-before-commit rule stays in the repository, though no agent file carries it anymore.

It refuses, and changes nothing:

• when you run it from a linked worktree, rather than the main checkout;
• while any linked worktree is registered, including a finished checkout you kept;
• while the resource ledger records provisioned resources, because those entries hold their only destroy commands. Reclaim them with discern worktree prune first. An entry marked prunable = false needs the project's own teardown;
• when it can't plan the Git configuration cleanup.

In a terminal, uninstall asks you to confirm. Without terminal input, under --plain, in CI, or with --json or --markdown, it needs --yes, and otherwise refuses with confirmation_required. It cleans up the Git configuration first, and if that fails, it removes no project files and reports apply_failed.

Uninstall runs only from the command line, and makes no remote change. discern never installs Git hooks, so your hooks stay as they are. Remove the installed program separately, once no other project on the computer needs it. Maintain or remove discern walks through the decision and the removal.

• Proof: what passing checks establish, and why later edits make that evidence stale.
• Licenses: the authorship boundary, and what you're responsible for when you redistribute.
• Platforms and providers: the exact files for each coding tool.
• Use discern alongside other agent tools: the decisions to make when another tool writes into the same files.
• What stays on your machine: what discern runs, records, and writes, and what never leaves your computer.