briar-cli 1.1.45__tar.gz → 1.1.46__tar.gz

{briar_cli-1.1.45 → briar_cli-1.1.46}/.gitignore

@@ -31,3 +31,6 @@ config.json
 
 # Real-company runbooks + planning docs — kept local, not for public repo
 runbooks/
+
+# Local Claude Code workspace (worktrees, caches)
+.claude/

{briar_cli-1.1.45 → briar_cli-1.1.46}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: briar-cli
-Version: 1.1.45
+Version: 1.1.46
 Summary: Terminal client for the Briar agent-orchestration API.
 Project-URL: Homepage, https://usebriar.com
 Project-URL: Source, https://github.com/iklobato/briar
@@ -129,7 +129,7 @@ export ANTHROPIC_API_KEY=sk-ant-...        # LLM key comes from the environment
 # 2. Mine a repo's PR history into a knowledge blob
 briar extract --company acme \
     --include pr-archaeology \
-    --pr-repo acme-co/acme-app --pr-max 50
+    --repo acme-co/acme-app --max 50
 
 # 3. Read it back
 briar context get knowledge:acme
@@ -137,6 +137,30 @@ briar context get knowledge:acme
 
 > **Telemetry:** `briar` ships with opt-out error/usage analytics (Sentry). No prompts, file contents, ticket keys, repo names, paths, or secret values ever leave the machine. Turn it off any time with `briar telemetry off`, `BRIAR_TELEMETRY=off`, or `DO_NOT_TRACK=1`.
 
+### Less typing: shared flags, project config, inference
+
+briar resolves every flag through one chain — **CLI flag > env var > project config > built-in default** — so the stable values move off the command line:
+
+```toml
+# .briar.toml (or [tool.briar] in pyproject.toml), searched upward from cwd
+company = "acme"
+store   = "postgres"
+
+[repo]
+owner = "acme-co"
+repo  = "acme-app"
+```
+
+With that file present, and inside the git checkout, the same extract is just:
+
+```bash
+briar extract --include pr-archaeology        # company + repo come from config/git
+```
+
+- **Canonical extractor flags.** One shared knob per concept — `--repo`, `--since-days`, `--max`, `--top-n`, `--sample`, `--authors-allow/-block`, `--assignees-allow/-block` — applies to every extractor selected with `--include`. The old per-extractor flags (`--pr-repo`, `--risk-since-days`, …) still work but are hidden from `-h`; run `briar extract --advanced-help` to see them.
+- **Inference.** `--owner`/`--repo` are read from the git `origin` remote when neither the flag nor config supplies them.
+- A per-extractor override always wins over the shared flag when both are given.
+
 ---
 
 ## What you can do
@@ -147,8 +171,8 @@ briar context get knowledge:acme
 # PRs + AWS infra in one shot, filtered to your team
 briar extract --company acme \
     --include pr-archaeology --include aws-infra \
-    --pr-repo acme-co/acme-app \
-    --pr-authors-allow alice --pr-authors-allow bob \
+    --repo acme-co/acme-app \
+    --authors-allow alice --authors-allow bob \
     --aws-extract-region us-east-1 \
     --aws-extract-service ecs --aws-extract-service rds
 
@@ -161,12 +185,11 @@ FIREFLIES_ACME_API_KEY=ff_xxx briar extract --company acme \
     --include meeting-digest --meeting-since-days 14 \
     --meeting-attendee-allow alice@acme.com
 
-# Code-quality signal from git history + the repo-host API
-briar extract --company acme \
-    --include defect-hotspots --risk-repo acme-co/acme-app \
-    --include pr-hygiene --prhygiene-repo acme-co/acme-app \
-    --include review-nits --nits-repo acme-co/acme-app \
-    --include ci-health --cihealth-repo acme-co/acme-app
+# Code-quality signal from git history + the repo-host API.
+# One --repo feeds every selected extractor.
+briar extract --company acme --repo acme-co/acme-app \
+    --include defect-hotspots --include pr-hygiene \
+    --include review-nits --include ci-health
 ```
 
 **Code-quality extractors** (all `--provider github|bitbucket`): `defect-hotspots`
@@ -181,8 +204,8 @@ briar extract --company acme \
 ```bash
 # Merge a knowledge index into CLAUDE.md; full detail lands in
 # .briar/knowledge/<company>.md for the agent to read when relevant.
-briar extract --company acme --include defect-hotspots --include ci-health \
-    --risk-repo acme-co/acme-app --cihealth-repo acme-co/acme-app \
+briar extract --company acme --repo acme-co/acme-app \
+    --include defect-hotspots --include ci-health \
     --merge-claude-md
 ```
 
@@ -254,33 +277,40 @@ Plus `briar context` (local knowledge blobs), `briar dashboard` (read-only HTML
 ### Repeatable flags — fan out across repos, projects, services
 
 Most list-style flags accept multiple occurrences: repeat the flag, once
-per value (there's no comma form — `--pr-repo a,b` is one repo named
-`a,b`). Mix them to cover a whole fleet in a single command.
+per value (there's no comma form — `--repo a,b` is one repo named `a,b`).
+The canonical `--repo` feeds every extractor selected with `--include`.
 
 ```bash
-# Mine several repos, keep the team's PRs, drop the bots, across two boards.
-# --pr-max applies per repo; author allow/block compose as allow ∩ ¬block.
+# Mine several repos, keep the team's PRs, drop the bots — one --repo,
+# every selected extractor. --max applies per repo; author allow/block
+# compose as allow ∩ ¬block.
 briar extract --company acme \
-    --include pr-archaeology --include active-tickets \
-    --tracker jira \
-    --pr-repo acme-co/web --pr-repo acme-co/api --pr-repo acme-co/mobile \
-    --pr-max 75 \
-    --pr-authors-block "dependabot[bot]" --pr-authors-block "renovate[bot]" \
-    --ticket-project ACME --ticket-project PLAT
-
-# Scaffold a triage flow from two sources, filtered by author + assignee.
-# Each tracker source carries its own repeatable *-authors/assignees-*.
+    --include pr-archaeology --include defect-hotspots \
+    --repo acme-co/web --repo acme-co/api --repo acme-co/mobile \
+    --max 75 \
+    --authors-block "dependabot[bot]" --authors-block "renovate[bot]"
+
+# Scaffold a triage flow from two sources — one shared author/assignee
+# filter applies to every --source.
 briar scaffold implementation --prefix acme-triage \
     --source github --source jira \
     --owner acme-co --repo acme-app --github-secret-id <uuid> \
-    --github-authors-block "dependabot[bot]" \
-    --github-assignees-allow alice --github-assignees-allow bob \
+    --authors-block "dependabot[bot]" \
+    --assignees-allow alice --assignees-allow bob \
     --jira-project ACME --jira-project PLAT --jira-secret-id <uuid> \
     --auth-mode pat
 ```
 
-The same lists map onto runbook YAML as arrays — e.g. `pr_repo:
-[acme-co/web, acme-co/api]` is two `--pr-repo` flags.
+The same lists map onto runbook YAML as arrays — e.g. `repo:
+[acme-co/web, acme-co/api]` under an extractor's `args:`.
+
+> **Divergent identifiers in one run.** Some extractors key off a tracker
+> *project* (`active-tickets`, `ticket-archaeology`) rather than an
+> `owner/repo` slug. When you run those alongside repo-based extractors in
+> a single invocation and they need *different* values, reach for the
+> per-extractor override flags (`--ticket-project`, `--pr-repo`, … — listed
+> by `briar extract --advanced-help`), or split into two invocations. The
+> runbook YAML models this cleanly: one `args:` block per extractor.
 
 ### Handy patterns
 

{briar_cli-1.1.45 → briar_cli-1.1.46}/README.md

@@ -37,7 +37,7 @@ export ANTHROPIC_API_KEY=sk-ant-...        # LLM key comes from the environment
 # 2. Mine a repo's PR history into a knowledge blob
 briar extract --company acme \
     --include pr-archaeology \
-    --pr-repo acme-co/acme-app --pr-max 50
+    --repo acme-co/acme-app --max 50
 
 # 3. Read it back
 briar context get knowledge:acme
@@ -45,6 +45,30 @@ briar context get knowledge:acme
 
 > **Telemetry:** `briar` ships with opt-out error/usage analytics (Sentry). No prompts, file contents, ticket keys, repo names, paths, or secret values ever leave the machine. Turn it off any time with `briar telemetry off`, `BRIAR_TELEMETRY=off`, or `DO_NOT_TRACK=1`.
 
+### Less typing: shared flags, project config, inference
+
+briar resolves every flag through one chain — **CLI flag > env var > project config > built-in default** — so the stable values move off the command line:
+
+```toml
+# .briar.toml (or [tool.briar] in pyproject.toml), searched upward from cwd
+company = "acme"
+store   = "postgres"
+
+[repo]
+owner = "acme-co"
+repo  = "acme-app"
+```
+
+With that file present, and inside the git checkout, the same extract is just:
+
+```bash
+briar extract --include pr-archaeology        # company + repo come from config/git
+```
+
+- **Canonical extractor flags.** One shared knob per concept — `--repo`, `--since-days`, `--max`, `--top-n`, `--sample`, `--authors-allow/-block`, `--assignees-allow/-block` — applies to every extractor selected with `--include`. The old per-extractor flags (`--pr-repo`, `--risk-since-days`, …) still work but are hidden from `-h`; run `briar extract --advanced-help` to see them.
+- **Inference.** `--owner`/`--repo` are read from the git `origin` remote when neither the flag nor config supplies them.
+- A per-extractor override always wins over the shared flag when both are given.
+
 ---
 
 ## What you can do
@@ -55,8 +79,8 @@ briar context get knowledge:acme
 # PRs + AWS infra in one shot, filtered to your team
 briar extract --company acme \
     --include pr-archaeology --include aws-infra \
-    --pr-repo acme-co/acme-app \
-    --pr-authors-allow alice --pr-authors-allow bob \
+    --repo acme-co/acme-app \
+    --authors-allow alice --authors-allow bob \
     --aws-extract-region us-east-1 \
     --aws-extract-service ecs --aws-extract-service rds
 
@@ -69,12 +93,11 @@ FIREFLIES_ACME_API_KEY=ff_xxx briar extract --company acme \
     --include meeting-digest --meeting-since-days 14 \
     --meeting-attendee-allow alice@acme.com
 
-# Code-quality signal from git history + the repo-host API
-briar extract --company acme \
-    --include defect-hotspots --risk-repo acme-co/acme-app \
-    --include pr-hygiene --prhygiene-repo acme-co/acme-app \
-    --include review-nits --nits-repo acme-co/acme-app \
-    --include ci-health --cihealth-repo acme-co/acme-app
+# Code-quality signal from git history + the repo-host API.
+# One --repo feeds every selected extractor.
+briar extract --company acme --repo acme-co/acme-app \
+    --include defect-hotspots --include pr-hygiene \
+    --include review-nits --include ci-health
 ```
 
 **Code-quality extractors** (all `--provider github|bitbucket`): `defect-hotspots`
@@ -89,8 +112,8 @@ briar extract --company acme \
 ```bash
 # Merge a knowledge index into CLAUDE.md; full detail lands in
 # .briar/knowledge/<company>.md for the agent to read when relevant.
-briar extract --company acme --include defect-hotspots --include ci-health \
-    --risk-repo acme-co/acme-app --cihealth-repo acme-co/acme-app \
+briar extract --company acme --repo acme-co/acme-app \
+    --include defect-hotspots --include ci-health \
     --merge-claude-md
 ```
 
@@ -162,33 +185,40 @@ Plus `briar context` (local knowledge blobs), `briar dashboard` (read-only HTML
 ### Repeatable flags — fan out across repos, projects, services
 
 Most list-style flags accept multiple occurrences: repeat the flag, once
-per value (there's no comma form — `--pr-repo a,b` is one repo named
-`a,b`). Mix them to cover a whole fleet in a single command.
+per value (there's no comma form — `--repo a,b` is one repo named `a,b`).
+The canonical `--repo` feeds every extractor selected with `--include`.
 
 ```bash
-# Mine several repos, keep the team's PRs, drop the bots, across two boards.
-# --pr-max applies per repo; author allow/block compose as allow ∩ ¬block.
+# Mine several repos, keep the team's PRs, drop the bots — one --repo,
+# every selected extractor. --max applies per repo; author allow/block
+# compose as allow ∩ ¬block.
 briar extract --company acme \
-    --include pr-archaeology --include active-tickets \
-    --tracker jira \
-    --pr-repo acme-co/web --pr-repo acme-co/api --pr-repo acme-co/mobile \
-    --pr-max 75 \
-    --pr-authors-block "dependabot[bot]" --pr-authors-block "renovate[bot]" \
-    --ticket-project ACME --ticket-project PLAT
-
-# Scaffold a triage flow from two sources, filtered by author + assignee.
-# Each tracker source carries its own repeatable *-authors/assignees-*.
+    --include pr-archaeology --include defect-hotspots \
+    --repo acme-co/web --repo acme-co/api --repo acme-co/mobile \
+    --max 75 \
+    --authors-block "dependabot[bot]" --authors-block "renovate[bot]"
+
+# Scaffold a triage flow from two sources — one shared author/assignee
+# filter applies to every --source.
 briar scaffold implementation --prefix acme-triage \
     --source github --source jira \
     --owner acme-co --repo acme-app --github-secret-id <uuid> \
-    --github-authors-block "dependabot[bot]" \
-    --github-assignees-allow alice --github-assignees-allow bob \
+    --authors-block "dependabot[bot]" \
+    --assignees-allow alice --assignees-allow bob \
     --jira-project ACME --jira-project PLAT --jira-secret-id <uuid> \
     --auth-mode pat
 ```
 
-The same lists map onto runbook YAML as arrays — e.g. `pr_repo:
-[acme-co/web, acme-co/api]` is two `--pr-repo` flags.
+The same lists map onto runbook YAML as arrays — e.g. `repo:
+[acme-co/web, acme-co/api]` under an extractor's `args:`.
+
+> **Divergent identifiers in one run.** Some extractors key off a tracker
+> *project* (`active-tickets`, `ticket-archaeology`) rather than an
+> `owner/repo` slug. When you run those alongside repo-based extractors in
+> a single invocation and they need *different* values, reach for the
+> per-extractor override flags (`--ticket-project`, `--pr-repo`, … — listed
+> by `briar extract --advanced-help`), or split into two invocations. The
+> runbook YAML models this cleanly: one `args:` block per extractor.
 
 ### Handy patterns
 

{briar_cli-1.1.45 → briar_cli-1.1.46}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "briar-cli"
-version = "1.1.45"
+version = "1.1.46"
 description = "Terminal client for the Briar agent-orchestration API."
 readme = "README.md"
 requires-python = ">=3.10"

{briar_cli-1.1.45 → briar_cli-1.1.46}/src/briar/cli.py

@@ -10,6 +10,11 @@ from __future__ import annotations
 
 import warnings
 
+# E402 is expected here: the warnings filter below MUST run before any
+# pydantic-importing module loads, so the rest of the imports follow it.
+# ruff: noqa: E402
+
+
 # pydantic's plugin loader scans installed packages for plugins at import
 # time. When logfire is installed but its pinned opentelemetry-sdk symbol
 # drifts (ReadableLogRecord was renamed upstream), the loader emits a
@@ -101,6 +106,25 @@ def _build_parser(commands: Dict[str, Command]) -> argparse.ArgumentParser:
     return parser
 
 
+def _warn_legacy_flags(raw_argv: List[str], log: logging.Logger) -> None:
+    """One consolidated stderr note when the command line uses a legacy
+    per-extractor / per-source flag that a canonical flag now covers.
+
+    A plain print, NOT a `warnings.warn` — the test suite runs with
+    `filterwarnings=error`, and this is user guidance, not a code smell."""
+    from briar.extract.canonical import legacy_flag_suggestions
+
+    suggestions = legacy_flag_suggestions(raw_argv)
+    if not suggestions:
+        return
+    pairs = ", ".join(f"{old} → {new}" for old, new in sorted(suggestions.items()))
+    print(
+        f"note: these flags are deprecated in favour of shared canonical flags: {pairs}. " "They still work; see `briar extract --advanced-help`.",
+        file=sys.stderr,
+    )
+    log.debug("legacy-flags: %s", pairs)
+
+
 def _install_default_journal(log: logging.Logger) -> None:
     """Install the process-wide default journal. Honours
     BRIAR_JOURNAL=off to disable entirely; otherwise wires the
@@ -197,6 +221,25 @@ def main(argv: Optional[List[str]] = None) -> int:
     commands = CommandRegistry.build()
     parser = _build_parser(commands)
 
+    # Fold project config (.briar.toml / [tool.briar]) + env into the
+    # parser defaults so a bare command inherits stable values (company,
+    # store, repo, model, …) and explicit flags still override. Skipped
+    # for help/usage so `briar -h` touches no config file.
+    if not metadata_only:
+        from briar.config import apply_config_defaults, load_project_config
+
+        satisfied = apply_config_defaults(parser, load_project_config())
+        if satisfied:
+            log.debug("config: satisfied defaults for %s", sorted(set(satisfied)))
+
+        # Below config in the precedence chain: infer --owner/--repo from
+        # the local git `origin` remote for whatever config didn't supply.
+        from briar.infer import apply_inference_defaults
+
+        inferred = apply_inference_defaults(parser, satisfied)
+        if inferred:
+            log.debug("infer: filled %s from git remote", sorted(set(inferred)))
+
     normalised: List[str] = []
     for flag, value in kv.items():
         normalised.extend([flag, value])
@@ -205,6 +248,8 @@ def main(argv: Optional[List[str]] = None) -> int:
     args = parser.parse_args(normalised)
     log.debug("dispatching command=%s args=%r", args.command, vars(args))
 
+    _warn_legacy_flags(raw_argv, log)
+
     # Wrap dispatch in a telemetry span so duration + outcome land
     # in one place. The span captures uncaught exceptions, scrubs
     # them, and ships an error event — then re-raises into the

{briar_cli-1.1.45 → briar_cli-1.1.46}/src/briar/commands/extract.py

@@ -12,6 +12,7 @@ from briar.commands.base import Command
 from briar.errors import CliError
 from briar.extract import EXTRACTORS
 from briar.extract.base import ExtractedSection
+from briar.extract.canonical import AdvancedHelpAction, apply_canonical, hide_canonicalised_flags, register_canonical_flags
 from briar.extract.claude_md import ClaudeMdMerger
 from briar.extract.composer import render_json, render_markdown
 from briar.storage import KNOWLEDGE_STORE_NAMES, make_store
@@ -46,8 +47,12 @@ class CommandExtract(Command):
             choices=sorted(EXTRACTORS.keys()),
             help="Which extractor(s) to run (repeatable; default: all available)",
         )
+        # `--store` is the name every other command uses; `--storage` is
+        # kept as an alias so existing scripts keep working.
         parser.add_argument(
+            "--store",
             "--storage",
+            dest="storage",
             default="file",
             choices=list(KNOWLEDGE_STORE_NAMES),
             help="Where to write the result (default: file)",
@@ -65,8 +70,20 @@ class CommandExtract(Command):
             default="./CLAUDE.md",
             help="CLAUDE.md to merge the knowledge index into (only used with --merge-claude-md)",
         )
+        parser.add_argument(
+            "--advanced-help",
+            action=AdvancedHelpAction,
+            help="Show the full per-extractor override flags and exit.",
+        )
+        # Canonical flags first (the headline surface), then the
+        # per-extractor private flags. The private flags stay registered
+        # for back-compat + the rare same-invocation-divergent case, but
+        # `hide_canonicalised_flags` suppresses the redundant ones from
+        # `-h` so the default help shows just the canonical + core knobs.
+        register_canonical_flags(parser)
         for ext in EXTRACTORS.values():
             ext.add_arguments(parser)
+        hide_canonicalised_flags(parser)
 
     def run(self, args: argparse.Namespace) -> int:
         selected = args.include or list(EXTRACTORS.keys())
@@ -74,6 +91,9 @@ class CommandExtract(Command):
         sections: List[ExtractedSection] = []
         for name in selected:
             ext = EXTRACTORS[name]
+            # Fan the canonical flags (--repo, --max, …) out to this
+            # extractor's private dests before availability / extraction.
+            apply_canonical(args, ext)
             if not ext.is_available(args):
                 print(f"  skipped {name}  (not available in this env)")
                 continue

briar_cli-1.1.46/src/briar/config.py

@@ -0,0 +1,208 @@
+"""Project config — `.briar.toml` (or `[tool.briar]` in pyproject.toml).
+
+Most flags repeat the same stable values on every invocation: the
+company, the store backend, the repo owner/slug, the agent model, the
+git identity. This module lets a project declare them once so the
+day-to-day command stops carrying them.
+
+Resolution precedence, highest first:
+
+    CLI flag  >  env var  >  project config  >  built-in default
+
+The mechanism is deliberately boring: `apply_config_defaults` rewrites
+each matching argparse action's `default` (and clears `required` when a
+value is found) BEFORE parsing, so an explicit CLI flag still wins by the
+normal argparse rule "an explicitly-passed option overrides its default".
+
+Config layout (`.briar.toml` keys are top-level; in pyproject.toml they
+live under `[tool.briar]`):
+
+    company = "acme"
+    store   = "postgres"
+    root    = "./knowledge"
+    tracker = "jira"
+
+    [repo]
+    owner    = "acme-co"
+    repo     = "acme-app"
+    provider = "github"
+
+    [agent]
+    model          = "claude-sonnet-4-6"
+    git_user_name  = "acme-bot"
+    git_user_email = "bot@acme.com"
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import os
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+log = logging.getLogger(__name__)
+
+_CONFIG_FILENAME = ".briar.toml"
+_PYPROJECT = "pyproject.toml"
+
+
+@dataclass(frozen=True)
+class _ConfigSpec:
+    """One config-satisfiable flag: the argparse dest it fills, the env
+    var that overrides config, and the (section, key) path into the
+    config dict. A top-level key uses section=""."""
+
+    dest: str
+    env: Optional[str]
+    section: str
+    key: str
+
+
+# The flags a project config / env may satisfy. `storage` is extract's
+# dest for the store backend (aliased --store); `store` covers every
+# other command. `knowledge` is agent's file-root dest, fed by the same
+# `root` config key.
+_CONFIG_SPECS: Tuple[_ConfigSpec, ...] = (
+    _ConfigSpec("company", "BRIAR_COMPANY", "", "company"),
+    _ConfigSpec("store", "BRIAR_DEFAULT_STORE", "", "store"),
+    _ConfigSpec("storage", "BRIAR_DEFAULT_STORE", "", "store"),
+    _ConfigSpec("root", None, "", "root"),
+    _ConfigSpec("knowledge", None, "", "root"),
+    _ConfigSpec("tracker", None, "", "tracker"),
+    _ConfigSpec("owner", None, "repo", "owner"),
+    _ConfigSpec("repo", None, "repo", "repo"),
+    _ConfigSpec("provider", None, "repo", "provider"),
+    _ConfigSpec("model", None, "agent", "model"),
+    _ConfigSpec("git_user_name", None, "agent", "git_user_name"),
+    _ConfigSpec("git_user_email", None, "agent", "git_user_email"),
+)
+
+
+def find_config_file(start: Optional[Path] = None) -> Optional[Path]:
+    """Nearest `.briar.toml` or pyproject.toml carrying `[tool.briar]`,
+    searching from `start` (default cwd) up to the filesystem root.
+    Returns None when neither is found."""
+    here = (start or Path.cwd()).resolve()
+    for directory in [here, *here.parents]:
+        dedicated = directory / _CONFIG_FILENAME
+        if dedicated.is_file():
+            return dedicated
+        pyproject = directory / _PYPROJECT
+        if pyproject.is_file() and _has_tool_briar(pyproject):
+            return pyproject
+    return None
+
+
+def _has_tool_briar(pyproject: Path) -> bool:
+    try:
+        with pyproject.open("rb") as handle:
+            return "briar" in tomllib.load(handle).get("tool", {})
+    except (OSError, tomllib.TOMLDecodeError):
+        return False
+
+
+def load_project_config(start: Optional[Path] = None) -> Dict[str, object]:
+    """The briar config section as a dict, or {} when no config file is
+    found / it cannot be parsed. For `.briar.toml` the whole file is the
+    section; for pyproject.toml it is `[tool.briar]`."""
+    path = find_config_file(start)
+    if path is None:
+        return {}
+    try:
+        with path.open("rb") as handle:
+            data = tomllib.load(handle)
+    except (OSError, tomllib.TOMLDecodeError) as exc:
+        log.warning("config: failed to read %s — ignoring (%s)", path, exc)
+        return {}
+    if path.name == _PYPROJECT:
+        return dict(data.get("tool", {}).get("briar", {}))
+    return dict(data)
+
+
+def _config_value(config: Dict[str, object], spec: _ConfigSpec) -> Optional[object]:
+    if spec.section:
+        section = config.get(spec.section)
+        if not isinstance(section, dict):
+            return None
+        return section.get(spec.key)
+    return config.get(spec.key)
+
+
+def _resolve(spec: _ConfigSpec, config: Dict[str, object]) -> Optional[object]:
+    """env wins over config; None when neither provides a value."""
+    if spec.env:
+        env_value = os.environ.get(spec.env)
+        if env_value:
+            return env_value
+    return _config_value(config, spec)
+
+
+def _iter_subparsers(parser: argparse.ArgumentParser):
+    """Yield every (sub)parser in the tree, including the root."""
+    yield parser
+    for action in parser._actions:
+        if isinstance(action, argparse._SubParsersAction):
+            for sub in action.choices.values():
+                yield from _iter_subparsers(sub)
+
+
+def _derive_repo_slug(config: Dict[str, object]) -> Optional[str]:
+    """`owner/repo` from the `[repo]` section, or None if incomplete."""
+    section = config.get("repo")
+    if not isinstance(section, dict):
+        return None
+    owner, repo = section.get("owner"), section.get("repo")
+    if owner and repo:
+        return f"{owner}/{repo}"
+    return None
+
+
+def _repo_list_value(config: Dict[str, object]) -> Optional[List[str]]:
+    """Value for an append-style `--repo` (the canonical extract flag),
+    which wants a list of `owner/repo` slugs: prefer an explicit `repos`
+    array, else the single slug derived from `[repo]`."""
+    repos = config.get("repos")
+    if isinstance(repos, list) and repos:
+        return [str(r) for r in repos]
+    slug = _derive_repo_slug(config)
+    return [slug] if slug else None
+
+
+def _value_for_action(action: argparse.Action, config: Dict[str, object]) -> Optional[object]:
+    """The config/env value appropriate to this action, or None when the
+    config does not speak to it. Shape-aware: an append `--repo` gets a
+    list of slugs, a scalar `--repo` gets the bare repo name."""
+    if action.dest == "repo" and isinstance(action, argparse._AppendAction):
+        return _repo_list_value(config)
+    for spec in _CONFIG_SPECS:
+        if spec.dest == action.dest:
+            value = _resolve(spec, config)
+            if value is not None:
+                return value
+    return None
+
+
+def apply_config_defaults(
+    parser: argparse.ArgumentParser,
+    config: Optional[Dict[str, object]] = None,
+) -> List[str]:
+    """Fold env + project config into the parser as new defaults so a
+    bare command inherits them and an explicit flag still overrides.
+
+    Mutates matching actions' `default` and clears their `required` when
+    a value is found. Returns the list of dests that were satisfied (for
+    logging / tests)."""
+    resolved = {} if config is None else config
+    satisfied: List[str] = []
+    for sub in _iter_subparsers(parser):
+        for action in sub._actions:
+            value = _value_for_action(action, resolved)
+            if value is None:
+                continue
+            action.default = value
+            action.required = False
+            satisfied.append(action.dest)
+    return satisfied