Maintain or remove discern

discerndiscern↗A tool that installs and runs an agent development practice in a project.'s setup belongs to your project. You can inspect it, keep it current, or remove its wiring while retaining the instructions, skills, and project knowledge you have written.

Choose the task you need: diagnose a problem, format discern's files, check releases, upgrade, or remove discern. Your agent can handle most maintenance; removal includes a terminal operation for you.

When an integration or command stops working, you can ask:

Check this project's discern installation and explain what's wrong. Repair what you can within the existing setup, then tell me whether anything needs access, a restart, or a decision from me.

Your agent starts with discern doctor. Doctor is read-only: it checks configuration, required commands, generated files, integrations, and other parts of the installation, then names the recovery for anything it finds.

A missing command and a broken configuration need different fixes. The agent should explain the observed problem before changing settings, apply the reported remedy, and run doctor again. A passing result establishes the installation checks; a repaired coding-tool connection also needs a successful call from a fresh session.

For a bug report, discern doctor --json captures a structured result. Troubleshooting helps match a symptom to a recovery.

If your instructions, mapMap↗The project's account of how its software works and why., work ledger, or discern.toml have become hard to scan, ask:

Format the files discern manages, review the changes, and bring them back through the project's checks.

In the task's worktreeWorktree↗A separate working copy and branch for one effort., the agent previews discern tidy --dry-run and applies discern tidy. The planner parses every target before writing. A malformed file stops the run without changing the targets, so the agent can correct it first.

Tidy covers the configured instruction sources, map, TODO ledger, and root config. It does not format application source, authored skills, generated agent files, or arbitrary repository files. Your project's own formatter remains responsible for those.

The agent reviews the diff, prepares and commits it, and runs the gateGate↗The configured checks a change must satisfy for ordinary completion.. A second tidy preview should report no changes. For a narrower task, discern tidy md or discern tidy toml formats only the selected type.

Ask your agent to check for updates, choose Check for updates from the deskDesk↗An interactive view of the project's tasks and the actions available for them., or run:

discern releases

The release page shows what's changed and whether an upgrade is available. The command opens it in your browser and prints the link so you can open it yourself if needed.

You can ask your agent to check and install an update in one request. If you only ask for a check, it will report what it finds and leave installation for you to decide. discern may remind you to check every couple of weeks.

Updating the installed program and updating a project's setup are separate steps. discern does not check the network for newer releases or replace its own binary.

Read the release notes before choosing an update.

Once you decide to install a newer version, use the supported installerInstaller↗The commands that set up and maintain discern in a project. described in installation and setup. It verifies the download checksum before replacing the binary. Open a new shell and check which program will run:

command -v discern
discern --version

Restart your coding-agent sessions after installation so they use the new version.

If the project reports a schema newer than the installed program, install a version that understands it. The schema describes the configuration format; an older program will refuse to stamp it backward.

Give your agent a bounded request:

Update this project's setup for the installed discern versiondiscern version↗The version of discern you are running, shown by discern --version.. Preview the changes, preserve our authored instructions and skills, and bring the upgrade back with its check results.

The agent uses an isolated worktree and reviews any existing edits before upgrading. It runs:

discern upgrade --check
discern upgrade --dry-run

--check reports pending adoption as well as migrationMigration↗A numbered step that updates a project's discern configuration format. and managed-scaffold changes. A migration brings older configuration into the format the running version expects. The dry run shows the previous and proposed meta.managed_version values and writes nothing.

Your agent runs discern upgrade, inspects the changes, and follows any partial-operation recovery. Your authored instructions, skills, scripts, and map remain project-owned; the plan identifies which managed settings or files need changes.

It then uses Finish and land a change to prepare the result for review. After landing, restart coding-tool sessions so their discern connection loads the installed version and current setup. The agent checks discern doctor, discern upgrade --check, and the fresh connection.

The upgrade is complete when the intended version is installed, no migrations remain, and the changed setup has passed its checks and works in a fresh session.

When you upgrade a project, commit the changes with your team. The managed_version field in discern.toml records the newest discern version used to update its managed files; it does not track what teammates have installed.

A teammate using an older discern version will see a message explaining how to update. They check releases, install the update, and restart their coding-agent sessions. They preview and apply discern upgrade in the project.

You can stop using discern without throwing away the project knowledge you built. Ask your agent to help prepare:

Help me remove discern from this repository. Identify unfinished work and resources that need attention, then explain the removal preview and what will remain for me to keep.

Uninstall is a CLI-only owner operation. The steps below happen in the main checkout after active work is resolved.

Read discern status. Land work you want to keep, and review any work you want discarded before explicitly dropping it. Follow the reported cleanup instructions for orphaned resources.

Uninstall refuses while any linked Git worktree remains registered, including a completed checkout you retained, or while the resource ledger records provisioned resources. Those records include the information needed to remove external resources, so deleting the records first would lose the cleanup instructions.

discern uninstall --dry-run

Review the complete plan. It removes discern's generated files, its entries in shared integration files, managed ignore and attribute blocks, and its Git-admin runtime state. It keeps discern.toml, your authored instructions and skills, map content, and recovery refs that may be the only remaining names for your commits.

If a shared setting cannot be removed safely, inspect that setting's ownership before changing it. The files and ownership reference explains the full boundary.

discern uninstall

Confirm the prompt after reviewing the plan. --yes is available for a non-interactive run you have already authorized.

Inspect git status and commit the removal through the repository's ordinary process. Keep recovery refs until you have reviewed the work they preserve.

Repository uninstall keeps the shared discern program installed. Other projects may still use it. If none do and you want to remove it, use which discern to identify the installed program before deleting it.

Removal is complete when the planned wiring has gone, your authored content remains, and no active resource is left without its cleanup record. Worktree troubleshooting covers cleanup that prevents uninstall.