Files and ownership

Use this reference to decide which files you or your agent may edit, which discerndiscern↗A tool that installs and runs an agent development practice in a project. may rewrite, and what remains after removal. Knowing those boundaries helps you protect the project's work while keeping generated files current.

Start with the ownership table for what to edit, or registered project paths to find a particular file. For local records, use Git configuration, runtime state, Git refs, or temporary files. Removing it all explains what uninstall keeps.

Project-owned files remain yours to change. Shared files contain entries discern maintains alongside yours. Generated files are rebuilt from their source, so your agent changes the source to keep an edit from being overwritten.

File ownershipFile ownership↗The rules for which parts of a file discern may maintain. is an operational term for edit and overwrite authority. It does not assign copyright or change a file's license.

The coding tool creates and maintains provider-local files, such as its machine-local permission settings. discern only ignores their registered paths. Other untracked provider files have no entry.

Each Git repository has one discern installation and one discern.toml at its root. In a monorepo, that file can assign different checks to different paths. A folder that is itself a separate Git repository can have its own installation. A second discern.toml in an ordinary nested folder has no effect.

The Discern-authored portions column identifies material covered by the Apache-2.0 project-payload grant. Project, user, provider, and third-party portions keep their existing terms. Ownership in this table tells you who may edit or overwrite a file; authorship determines its license.

Shared and generated artifacts also declare one provenance class:

• Context-loaded: unmarked. Agent files and skills load in full, so each marker would spend context tokens. Providers also render comments differently. Instructions and drift checks enforce ownership.
• Comment-incapable: no marker because JSON forbids comments.
• Comment-capable non-context: its marker identifies the source. By default, it also names discern and links to discern.sh. DISCERN_NO_ATTRIBUTION keeps the source and removes the product byline and link.

A missing marker does not make an artifact project-owned. Use the inventory below to identify its source before editing.

/** covers a directory. Provider-local remains visible so ignored files are not mistaken for Generated ones.

The table uses fresh-install defaults. An isolated workspace for one task (a Git worktreeWorktree↗A separate working copy and branch for one effort.) may use configured environment-file paths instead of .env; those files keep the same Shared and Apache-2.0 answers.

Path overrides change placement. The ownership bucket still determines edit and overwrite authority.

Agent files (AGENTS.md, CLAUDE.md, and GEMINI.md) are tracked for bare clones. discern done blocks stale copies. The tracked-refresh plan also covers discern's managed portions of tracked shared files, including generated attributes and provider integrations. done and accept require an empty plan before landing. After landing, acceptance materializes only ignored or local artifacts.

Project rules outside .gitattributes' discern markers remain unchanged, including nested and Git-local attributes. setup, refresh, and upgrade rebuild the block from discern.toml, the source-path registry, and the active agent registry. A rebuild replaces hand edits inside the block.

The managed block requests merge=discern-generated for every tracked declared generated artifact and live agent-file output. Doctor passes that same canonical population to git check-attr --stdin -z merge; Git decides each path's protection instead of block inspection. It reports unsafe values without rewriting rules. Set linguist_generated = true inside one [generated.<name>] table to mark only that group's paths as generated for GitHub. GitHub then hides them in diffs by default and excludes them from language statistics. The default is false.

Markdown inside discern's registered surfaces uses Git's built-in markdown diff driver. This covers configured map, instructions, skills, scripts, TODO, and brief paths plus active agent files. There is no repo-wide *.md rule: a project's README and other Markdown stay under the project's own attributes policy unless one of those paths is explicitly configured as a discern surface.

Materialized skills and provider-local state are ignored by exact registry path, leaving neighboring files unchanged. Add agent-file ignores outside the managed block if preferred. The currency check accepts a missing copy.

The ignore reconciler owns only its marked block and exact standalone rules that the current provider-artifact registry declares. Similar broad or retired rules outside the block remain project-owned. When [worktree].root resolves inside the repository, the managed block also ignores that exact nested directory; the default sibling worktree root needs no repository rule.

These are the only Git configuration entries discern writes. discern stores all of them in clone-local configuration.

The generated merge driver has one definition in the common clone config and is effective from the main checkout and every linked worktree. Reconciliation migrates redundant config.worktree copies. A fresh clone has the tracked attributes but not clone-local configuration; its first setup or discern refresh installs the shared driver. An identical unmarked remote fetch mapping is project-owned and remains unchanged.

These local working records live under discern/ inside Git's administrative directories. Your agent manages them through discern so checks, approvals, and recovery state stay consistent across sessions; leave them out of project commits and manual edits. A checkpointCheckpoint↗A review question presented when a relevant kind of change occurs. is a questionQuestion↗Something the agent is asked to judge about the project or a change. the agent must judge, and only the owner may authorize an unmet answer.

Durable state replacements share one interruption-safe policy; intentional moves and create-once publication remain separate.

Repository records use the common Git directory; worktree records disappear with that worktree. discern worktree park copies the current task wording into discern/parked-tasks/ before removing the worktree record; a successful discern start --from at the parked commit transfers the wording into the new worktree and removes the record. Await continuation records have a 7-day time limit and a 512-record repository cap. Removed worktree path evidence has a 90-day limit and a 256-record cap; it authorizes only an explicit prune offer for the recorded path. Guards enforce namespaceNamespace↗The default directory for the project's authored discern content., lifetime, and reset behavior.

Git stores drop recovery through ordinary refs under refs/discern/recovery/. Git can therefore choose its files-based or reftable storage format. The newest 32 refs keep committed tips reachable after their worktree branches are deleted. They remain local unless a person configures transport. discern uninstall leaves them in place because a ref may be the only remaining name for user-authored commits. Review and delete them with git update-ref -d <ref> when that recovery history is no longer needed.

Ordinary acceptance fast-forwards the trunkTrunk↗The shared branch that accepted work joins, usually main. and creates its marker under refs/worktree/discern/acceptance-transactions/<transaction-id> in the same ref transaction. An interrupted landing resumes from that marker and the worktree's journal without repeating the landing.

This local record supports update reminders and is shared by linked worktrees. Successful setup or upgrade starts the clock; opening release information resets it. A reminder can appear after 14 UTC calendar days. Viewing the reminder leaves it in place. Turning off the logbook does not affect it, and uninstall removes the record.

Uninstall never deletes a ref. Its result can suggest exact git update-ref -d '<ref>' commands for retained private refs. Keep their recovery evidence unless you have established it is no longer needed. Ordinary local branches remain visible as branches and receive no automatic cleanup suggestion.

Temporary artifacts use the operating system's temporary directory. They remain local evidence outside the project and its commits.

Registered temporary artifacts expire after 24 hours. A sweep inspects at most 500 matching entries and removes at most 500 expired entries per page. The repository coordinator runs at most one page per hour and retains a cursor so later pages continue through a large population. Only registered prefix-and-suffix combinations are eligible; unrelated temporary files are not supported sweep targets.

Repository-local crash reports use <git-common-dir>/discern/crash/<timestamp>-<pid>-<unique>.txt, mode 0600, with the newest 20 retained. A command-line crash exits 70; JSON uses error: "internal_error". An MCP tool crash returns an internal_error result without terminating the server. If repository-local storage is unavailable, the report uses the temporary crash family above. The report records the discern versiondiscern version↗The version of discern you are running, shown by discern --version., timestamp, attempted verb, platform, error name/message, and stack; it is local diagnostic evidence and can contain local paths.

For symptom-led preservation and cleanup, see Crashes and local state.

discern uninstall removes generated files, discern-owned Shared entries, the managed .gitignore and .gitattributes blocks, the whole discern/ runtime-state namespace under Git's administrative directories, the common generated-merge driver and its obsolete checkout-local copies, and only marked Proof note fetch mappings. Preview with discern uninstall --dry-run.

It keeps project-owned files, discern.toml, unmarked Git configuration, checkout-specific configuration the project still needs, and every ref. It reports retained private refs and optional exact cleanup commands without running them. It names Shared settings that it cannot clean without bundled templates. It refuses while any linked Git worktree remains registered, including a completed checkout you retained, or while the resource ledger records provisioned resources. Those entries hold their only destroy commands, so reclaim them with discern worktree prune first. Uninstall is CLI-only, performs no remote operation, and leaves normal Git hooks to run with Git's usual exit semantics. Remove the installed binary separately only when no other project on the machine needs it. Maintain or remove discern walks through the decision and removal.

The artifact ownership map links the registries and implementation behind this inventory. Use it when contributing to discern or checking how an ownership rule is enforced.

• Proof: what passing checks establishes and why later edits make that evidence stale.
• Licenses for project payloads: the authorship boundary and downstream redistribution responsibility.
• Platforms and providers: the exact file table per coding tool.
• Trust and your data: the network, telemetry, and execution contract on one screen.