diff --git a/.agents/phases/complete/173_docs_push_creds_split/00_phase.md b/.agents/phases/complete/173_docs_push_creds_split/00_phase.md
new file mode 100644
index 0000000..1d14599
--- /dev/null
+++ b/.agents/phases/complete/173_docs_push_creds_split/00_phase.md
@@ -0,0 +1,53 @@
+# Phase 173 — Docs-push credentials: split the username/token out of `BOR_DOCS_REPO`
+
+**Source:** owner audit of the production admin Settings panel (2026-10-10): `BOR_DOCS_REPO` is a plain-text row whose production value is a git URL with an embedded username + Gitea token (`https://user:token@host/…`) — a live credential leak on the settings page, the raw HTML, and the settings API.
+**Story:** n/a (owner-directed, chat-confirmed 2026-10-10)
+**Context:** `app/config.py` — the Docs push section (`docs_repo` L539, `docs_branch` L545, `docs_base_branch` L549, `docs_work_dir` L554; the branch validator L831–846 requires non-empty branches only while `docs_repo` is set; `docs_configured` L902–906 is the 409 inert-switch on `docs_repo` alone — **untouched**), `.env.example` L229–234 (the Docs push block — commented optional vars), `app/core/settings_catalog.py` L303–308 (the `Docs push` group: `docs_repo` L303, `docs_branch` L304, `docs_base_branch` L305–307, `docs_work_dir` L308) and the existing secret mechanism (`llm_api_key` L142 `secret=True`; `SECRETS` is DERIVED from `CATALOG` — a `secret=True` entry is write-only end-to-end: the API reports `is_set` + `value=null` (`app/api/admin_settings.py` L147), a blank PUT 422s (L273), and the phase-168/171 panel renders the row masked as `(stored)` with zero `settings.js` code), `scripts/git_sync.py` L320 (`run_git(argv, cwd)` — the ONLY git invocation site, A11; `subprocess.run(argv, cwd=cwd, capture_output=True, text=True)` L331 — no env today), `app/core/docs_push.py` (`push_document` — clone L104–116 / fetch / checkout / add / commit / push, every step via `run_git`; `DocsPushError` carries the full git stderr for logs), `app/api/doc_drafts.py` L299–316 (the push call site; phase 84 `sanitize_error` already strips echoed credentials from the 502 response — defense-in-depth, stays), `app/core/settings_overlay.py` (`load_overrides()` L93 — the raw `app_settings` DB map; `resolve_settings()` L239; `reset_state_for_tests()` L274), `app/main.py` L98–245 (`create_app()` the composition root; `app = create_app()` L245), `tests/unit/test_config.py`, `tests/unit/test_settings_catalog.py`, `tests/integration/test_admin_settings_api.py` + `test_admin_settings_live.py` (the generic set/reset/live-apply contract), `tests/e2e/test_admin_settings_panel.py` + `test_admin_settings_layout.py` (phase 168/171 — the regression set), `tests/e2e/test_response_to_docs.py` (phase 59 — the docs-push E2E).
+
+## Objective
+The docs-push remote's credentials live in their own settings — `BOR_DOCS_USER` (plain) and `BOR_DOCS_TOKEN` (write-only, masked like `BOR_LLM_API_KEY`) — while `BOR_DOCS_REPO` holds a clean URL. At push time the credentials travel as git's `GIT_CURL_USERNAME` / `GIT_CURL_PASSWORD` environment variables (never in the command line / process list), a one-time startup migration splits any legacy `://user:pass@` value into the new settings (DB rows shadow the env, `.env` is never rewritten), and a PUT guard refuses a credentials-bearing repo URL so the leak cannot be re-created from the UI. Anonymous pushes (no token) stay byte-identical to today.
+
+## Design (shared by all tasks — the executor reads this, not the chat)
+- **D1 — the three settings (task 01).** `docs_user: str = ""` and `docs_token: str = ""` in the Docs push section of `app/config.py` (directly after `docs_repo` L539, before `docs_branch` L545). Plain `str`, no validator (empty = "no credentials" is a valid state — the repo may be public/anonymous, exactly like today). `.env.example` L231–234 block gains `# BOR_DOCS_USER=` / `# BOR_DOCS_TOKEN=` (commented — optional, house style of the block). CATALOG: `docs_user` plain, `docs_token` **`secret=True`** (inserted directly after `docs_repo` L303, before `docs_branch` L304). The `SECRETS` derivation + the generic overlay + the phase-168/171 panel make `docs_token` a write-only, masked row with zero extra code (C1). No frontend code changes anywhere in this phase.
+- **D2 — the PUT guard (task 02).** In `app/api/admin_settings.py`, the `PUT` route refuses `docs_repo` values that embed credentials — a `://<user>:<pass>@` segment (regex `://[^/@:]+:[^@/]+@`) — with a 422 whose detail names the replacement (use the Docs user / Docs token fields, keep the URL clean). Everything else about the row is unchanged (it stays overridable, plain). `docs_token`'s API behavior is the EXISTING generic secret contract (GET `is_set`/`value=null`, blank PUT 422, DELETE resets) — task 02 pins it with integration assertions, it needs no new code.
+- **D3 — credentials on the wire (task 03).** `run_git` gains an optional `env: dict[str, str] | None = None` passed straight to `subprocess.run` — **the subprocess env-replacement trap**: when set, the dict REPLACES the parent environment, so `docs_push` must build it as `{**os.environ, …}` (a test asserts `PATH` survives). `push_document` gains `user: str = ""` / `token: str = ""`; when `token.strip()` is non-empty, EVERY git step of the sequence (clone, both fetches, checkout, add, commit, push) gets `env = {**os.environ, "GIT_CURL_USERNAME": user, "GIT_CURL_PASSWORD": token, "GIT_TERMINAL_PROMPT": "0"}` (git's documented HTTP credential env; `GIT_TERMINAL_PROMPT=0` fails fast instead of hanging a headless server on a prompt); when the token is empty, `env` stays `None` and the invocations are byte-identical to today (C5). The clean URL stays in the argv. `app/api/doc_drafts.py` passes `settings.docs_user` / `settings.docs_token`. `GIT_CURL_*` only takes effect for `http(s)` remotes; for `ssh://` / local-path remotes it is inert (accepted). Phase 84's `sanitize_error` on the 502 response is untouched (defense-in-depth).
+- **D4 — the legacy migration (task 04).** New module `app/core/settings_migrate.py` with `migrate_legacy_docs_creds() -> bool`: read the `app_settings` overrides; take the EFFECTIVE `docs_repo` (DB override if present, else env — i.e. `resolve_settings().docs_repo`); if it matches `://<user>:<pass>@` (both non-empty) AND there is no `docs_token` override yet, write three DB rows — `docs_repo` = the credential-stripped URL, `docs_user` = user, `docs_token` = pass — and log one INFO line (`settings: migrated embedded docs-push credentials out of docs_repo into docs_user/docs_token`); any other shape → no-op. Idempotent (a `docs_token` row already present → never clobber owner-set values). Called ONCE from `create_app()` (the composition root) after the DB is available. `.env` is never read for writing or rewritten — the DB rows shadow the env (the settings model's standing rule). Unit-tested against the overlay module's state + `reset_state_for_tests()`.
+- **D5 — the E2E (task 05).** `tests/e2e/test_docs_push_creds.py` — the phase's dedicated Playwright suite (AGENTS rule 4): the Docs push group shows a `Docs repo` text row, a `Docs user` text row, and a `Docs token` write-only row rendered masked (`(stored)`, not pre-filled, `type=password`); typing a token, saving, and reloading keeps the row masked and the typed token text is **absent from the entire page DOM** (the core assertion — the leak class this phase kills); resetting the token unsets it. The regression set (`test_admin_settings_panel.py`, `test_admin_settings_layout.py`, `test_response_to_docs.py`) stays green.
+- **NOT touched:** `frontend/` (no file), the `app_settings` table shape, `settings_overlay.py` internals, `docs_configured` / the 409 inert-switch, the branch validator, `git_sync.clone_or_pull` (sync path — no credential settings exist for it; out of scope), `sanitize_error` (phase 84), every other setting.
+
+## Dependencies
+— (none: the app is fully functional at the head of `complete/`; this phase builds on the committed phase-59 docs-push, phase-168/171 settings machinery, and phase-84 error sanitization)
+
+## Tasks
+1. `01_config_and_catalog.md` — `Settings.docs_user` / `docs_token` (default `""`) + the two CATALOG rows (`docs_token` `secret=True`) + `.env.example`; the config/catalog unit tests.
+2. `02_api_masking_and_guards.md` — integration pin of the `docs_token` write-only contract + the new `docs_repo` embedded-credentials PUT guard (422); the guard's unit/integration tests.
+3. `03_run_git_env_and_push.md` — `run_git(env=None)` + `push_document(user, token)` credential env on every git step (merged over `os.environ`; `None` when the token is empty) + the `doc_drafts.py` call site; the mocked-git unit tests.
+4. `04_legacy_creds_migration.md` — `app/core/settings_migrate.py` (idempotent, DB-shadowing, one log line) wired into `create_app()`; unit + integration tests.
+5. `05_e2e_docs_creds_masking.md` — `tests/e2e/test_docs_push_creds.py` (the phase's dedicated Playwright suite, AGENTS rule 4), the regression set, the full gates, the atomic commit.
+
+## Testing & Quality
+- **Unit:** `tests/unit/test_config.py` — `docs_user` / `docs_token` default `""`, env overrides, empty env stays `""` (no coercion). `tests/unit/test_settings_catalog.py` — the completeness pin holds with the two new fields; `docs_token` is in `SECRETS`, `docs_user` is in none of the derived sets. `tests/unit/test_git_sync.py` (or the existing `run_git` test home) — `env=None` leaves the subprocess call byte-identical; a passed env reaches `subprocess.run` verbatim. `tests/unit/test_docs_push.py` — token empty → every `run_git` call gets `env=None`; token set → every git step gets the 3-var env merged over `os.environ` (`PATH` present); `DocsPushError` propagation unchanged. `tests/unit/test_settings_migrate.py` — the 4 migration shapes (D4).
+- **Integration:** `tests/integration/test_admin_settings_api.py` / `test_admin_settings_live.py` — `docs_token` in `GET /api/admin/settings` (group `Docs push`, `secret=true`, `value=null`, `is_set` flips on PUT); PUT stores / DELETE resets / blank PUT 422 (the generic contract pinned for the new key); `docs_repo` PUT with `://user:pass@` → 422 naming the user/token fields, clean URLs pass. `tests/integration/test_docs_push_migrate.py` — seeded env `BOR_DOCS_REPO=https://u:pass@host/r.git`, no DB rows → after the migration runs, `resolve_settings().docs_repo` is `https://host/r.git`, `docs_user`/`docs_token` resolve from the DB; a second run is a no-op.
+- **E2E (AGENTS rule 4, task 05):** `tests/e2e/test_docs_push_creds.py`, run **in isolation** — per D5.
+- **Coverage:** **>90%** on `app/` (`uv run pytest --cov=app --cov-report=term-missing`).
+- **Lint/types:** `uv run ruff check . && uv run pyright`.
+
+## Completion Criteria
+- [ ] `GET /api/admin/settings` (admin) lists `docs_user` (plain) and `docs_token` (secret, `value=null`) in the `Docs push` group; the token value is NEVER in any response body.
+- [ ] `PUT /api/admin/settings` for `docs_repo` with a `://user:pass@` value → 422 naming the Docs user / Docs token fields; a clean URL passes.
+- [ ] With `docs_token` set, a docs push invokes git with `GIT_CURL_USERNAME` / `GIT_CURL_PASSWORD` / `GIT_TERMINAL_PROMPT=0` in the environment and a clean URL in the argv (unit-asserted via mocked `run_git`); with it empty, the `run_git` calls are byte-identical to today (`env=None`).
+- [ ] A legacy `://user:pass@` env value is split once at startup into `app_settings` rows (clean repo + user + token), `.env` untouched, a second run is a no-op; the INFO migration line is logged exactly once.
+- [ ] `uv run pytest` green (100% — every test in the project, pre-existing included), `app/` coverage >90%, ruff + pyright clean.
+- [ ] `uv run pytest tests/e2e/test_docs_push_creds.py -v --no-cov` green **in isolation**; `test_admin_settings_panel.py` + `test_admin_settings_layout.py` + `test_response_to_docs.py` green in isolation.
+- [ ] One atomic `--no-gpg-sign` Conventional Commit (e.g. `feat(settings): split docs-push credentials (BOR_DOCS_USER/BOR_DOCS_TOKEN) out of the repo URL — masked, env-wired, legacy auto-migration`); the phase dir moves to `.agents/phases/complete/`.
+- [ ] `README.md` and `AGENTS.md` are accurate and consistent with the project as it will stand after the phase (the final pass reviews both in full and fixes every inconsistency found, including pre-existing ones).
+
+## Documentation & Consistency (mandatory)
+The final pass reviews `README.md` and `AGENTS.md` in their entirety against the project as it will stand after the phase and fixes every inconsistency found — including pre-existing ones not caused by the phase. Tasks update both files whenever their own changes are user-visible (the `.env.example` block is the user-visible docs surface for this phase; the README's docs-push section gains the two new vars + a line that credentials in the repo URL are no longer supported).
+
+## Locked decisions (owner-confirmed 2026-10-10, chat)
+- **C1 — the split shape:** `docs_repo` (clean URL) + `docs_user` (plain `str`) + `docs_token` (`secret=True` in the CATALOG — reuses the existing write-only/masked mechanism end-to-end, `llm_api_key`-style). No new UI code: the panel renders both rows from the catalogue.
+- **C2 — the credential transport:** `GIT_CURL_USERNAME` / `GIT_CURL_PASSWORD` (+ `GIT_TERMINAL_PROMPT=0`) environment variables on the push sequence — never in the git argv / process list; applied only when `docs_token` is non-empty.
+- **C3 — the migration:** one-time at startup (`create_app()`), effective-value based, DB rows shadow the env, `.env` never rewritten, idempotent, one INFO log line.
+- **C4 — the guard:** `PUT docs_repo` with embedded credentials → 422 (the leak cannot be re-created via the UI).
+- **C5 — no behavior change for anonymous pushes:** empty `docs_token` → the git invocations are byte-identical to today (`env=None`).
diff --git a/.agents/phases/complete/173_docs_push_creds_split/01_config_and_catalog.md b/.agents/phases/complete/173_docs_push_creds_split/01_config_and_catalog.md
new file mode 100644
index 0000000..6914819
--- /dev/null
+++ b/.agents/phases/complete/173_docs_push_creds_split/01_config_and_catalog.md
@@ -0,0 +1,55 @@
+# Task 01 — The `docs_user` / `docs_token` settings + the catalogue rows + `.env.example`
+
+**Phase:** `173_docs_push_creds_split` · **Source:** owner audit of the production admin Settings panel (2026-10-10): `BOR_DOCS_REPO` leaks its embedded Gitea token in plain text; the credentials get their own settings.
+**Story:** n/a
+
+## Objective
+The two new settings exist in `app/config.py` (default `""`), in the admin catalogue (so the build's completeness pin stays green — a field without a `SettingMeta` fails the build, and the per-task gate runs the full suite), and in `.env.example`, so `BOR_DOCS_USER` / `BOR_DOCS_TOKEN` are first-class, documented knobs before anything consumes them. `docs_token` is `secret=True` — write-only, masked end-to-end via the EXISTING mechanism (C1); nothing else in the phase touches `frontend/`.
+
+## Work
+1. `app/config.py` — in the Docs push section, **directly after** the `docs_repo` block (L539) and **before** `docs_branch` (L545), add TWO fields, house docstring style (env var named, default, consumption point, off rule):
+   ```python
+   #: Docs-push remote username (phase 173, ``BOR_DOCS_USER``) — paired
+   #: with ``docs_token``; travels to git as the ``GIT_CURL_USERNAME``
+   #: environment variable (``app/core/docs_push.py``, task 03) — never
+   #: in the command line. Empty (default) = no credentials: the push
+   #: is anonymous/URL-credential-free, exactly as before this phase.
+   docs_user: str = ""
+   #: Docs-push remote token (phase 173, ``BOR_DOCS_TOKEN``) — write-only
+   #: (catalogue ``secret=True``): the API reports ``is_set`` and never
+   #: the value; the admin panel renders it masked. Travels to git as
+   #: ``GIT_CURL_PASSWORD`` (``app/core/docs_push.py``, task 03).
+   #: Empty (default) = the credential env is not set at all.
+   docs_token: str = ""
+   ```
+   No validator, no coercion — plain `str`; an empty value is a valid state (C1/C5). The L831–846 branch validator (branches required only while `docs_repo` is set) and `docs_configured` (L902–906) stay byte-identical.
+2. `.env.example` — in the Docs push block (L229–234), directly under `# BOR_DOCS_REPO=/path/to/docs-repo` (L231), add:
+   ```
+   # BOR_DOCS_USER=
+   # BOR_DOCS_TOKEN=
+   ```
+   (commented — optional, the block's house style; add one line to the block's comment: credentials in the repo URL are no longer supported — use BOR_DOCS_USER/BOR_DOCS_TOKEN).
+3. `app/core/settings_catalog.py` — in the `Docs push` group, **directly after** the `docs_repo` entry (L303) and **before** `docs_branch` (L304), add TWO entries:
+   ```python
+   "docs_user": SettingMeta("docs_user", "Docs push", "Docs user"),
+   "docs_token": SettingMeta(
+       "docs_token", "Docs push", "Docs token", secret=True
+   ),
+   ```
+   Nothing else — `SECRETS` / `RESTART_REQUIRED` / `NON_OVERRIDABLE` are DERIVED from `CATALOG` (module docstring): `docs_token` lands in `SECRETS` automatically, `docs_user` in none. Both are plain `str` → the overlay is generic (live, no restart). The panel row falls out of the catalogue with zero `settings.js` code (C1 — the phase-168/171 machinery renders a `secret=True` row masked as `(stored)`, `llm_api_key`-style).
+4. `tests/unit/test_settings_catalog.py` — the completeness pin (`set(CATALOG) == set(Settings.model_fields)`) must stay green with the two new fields; add the house-style assertions: `CATALOG["docs_user"]` sits in group `Docs push` with label `Docs user` and is in **none** of the derived sets; `CATALOG["docs_token"]` has label `Docs token`, `secret=True`, and **is** in `SECRETS`.
+5. `tests/unit/test_config.py` — add the house-style cases: (a) the DEFAULTS are `""` / `""` (no env set); (b) the env override — `BOR_DOCS_USER=alice` / `BOR_DOCS_TOKEN=tok` resolve to `"alice"` / `"tok"`; (c) the empty env values stay `""` (no coercion, no normalization away from empty — C5's anonymous state stays expressible).
+
+- ASSUMPTIONS: C1 (phase-locked) — the split shape; C5 (phase-locked) — empty token = no credential env, so the settings must NOT strip/coerce away the empty value at load.
+
+## Testing & Quality
+- Unit: `tests/unit/test_config.py` + `tests/unit/test_settings_catalog.py` green (`uv run pytest tests/unit/test_config.py tests/unit/test_settings_catalog.py -v --no-cov`).
+- Coverage: **>90%** on `app/` (the gate must stay green).
+- Lint/types: `uv run ruff check . && uv run pyright`.
+
+## Completion Criteria
+- [ ] `uv run pytest -k "docs" tests/unit/test_config.py tests/unit/test_settings_catalog.py -v --no-cov` green: defaults `""`, env overrides, empty stays `""`, the completeness pin holds, `docs_token` in `SECRETS`, `docs_user` in none.
+- [ ] `grep -n "BOR_DOCS_USER" .env.example` shows the line under `# BOR_DOCS_REPO=…` (commented).
+- [ ] `GET /api/admin/settings` (admin) lists `docs_user` + `docs_token` in the `Docs push` group — `docs_token` as `secret=true` with `value=null` (a quick curl, or the task-02 integration test).
+- [ ] `uv run pytest` green; ruff + pyright clean.
+- [ ] no behavior change in completed work (no other `Settings` field touched; `frontend/` untouched; `docs_configured` + the branch validator byte-identical).
diff --git a/.agents/phases/complete/173_docs_push_creds_split/02_api_masking_and_guards.md b/.agents/phases/complete/173_docs_push_creds_split/02_api_masking_and_guards.md
new file mode 100644
index 0000000..4b59577
--- /dev/null
+++ b/.agents/phases/complete/173_docs_push_creds_split/02_api_masking_and_guards.md
@@ -0,0 +1,45 @@
+# Task 02 — The `docs_token` write-only contract (pinned) + the `docs_repo` embedded-credentials guard
+
+**Phase:** `173_docs_push_creds_split` · **Source:** C2/C4 (phase-locked) — the token is write-only end-to-end via the existing mechanism; a credentials-bearing repo URL is refused on the way in so the leak cannot be re-created from the UI.
+**Story:** n/a
+
+## Objective
+The `docs_token` row's API behavior is the EXISTING generic secret contract — task 02 pins it with integration assertions for the new key (no new code expected). The ONE piece of new logic: the `PUT` route refuses `docs_repo` values with embedded credentials (C4), pointing the operator at the Docs user / Docs token fields.
+
+## Work
+1. `app/api/admin_settings.py` — in the `PUT` route, **before** the existing blank-secret 422 check (L273) or alongside it, add the `docs_repo` guard (a small module-level helper keeps the route readable — house style):
+   ```python
+   #: A git URL with embedded credentials (``://<user>:<pass>@``) — the
+   #: phase-173 leak class. Refused for ``docs_repo`` on the way in:
+   #: the credentials belong in ``docs_user`` / ``docs_token`` (C4).
+   _EMBEDDED_CREDS = re.compile(r"://[^/@:]+:[^@/]+@")
+
+   def _refuse_embedded_credentials(key: str, value: str) -> None:
+       if key == "docs_repo" and _EMBEDDED_CREDS.search(value):
+           raise HTTPException(
+               status_code=422,
+               detail=(
+                   "docs_repo must not contain embedded credentials — "
+                   "keep the URL clean and set them in the Docs user / "
+                   "Docs token fields instead"
+               ),
+           )
+   ```
+   Call it at the top of the per-key validation in the PUT route (after the payload is parsed, before store). Only `docs_repo` is guarded — `ssh://` URLs, local paths, and clean `https://` URLs pass untouched. (A legacy `.env` value with embedded credentials is NOT a PUT — the task-04 startup migration handles that path; the guard covers only new writes.)
+2. `tests/integration/test_admin_settings_api.py` (or `test_admin_settings_live.py` — match the file that owns the secret-row contract; the phase-172 pin is the template) — add the house-style cases for the new key:
+   - `GET /api/admin/settings` (admin): `docs_token` in group `Docs push`, `secret=true`, `value=null`, `is_set=false`; `docs_user` plain, `value=""`.
+   - `PUT docs_token` with a value → 200; `GET` → `is_set=true`, `value=null` (the value is **never** in the response body — assert the token text is absent from the raw response JSON).
+   - `PUT docs_token` with a blank value → 422 (the existing self-lockout guard — pinned for the new key).
+   - `DELETE docs_token` → `is_set=false` (reset to env — `""` by default).
+3. `tests/integration/test_admin_settings_api.py` — the guard's integration cases: `PUT docs_repo` `https://u:pass@gitea.example.com/o/r.git` → 422, detail mentions the Docs user / Docs token fields; `PUT docs_repo` `https://gitea.example.com/o/r.git` → 200 (clean passes); `PUT docs_repo` a local path (`/srv/docs-repo`) → 200 (untouched); a `user:` segment that is NOT `://user:pass@` (e.g. `https://sub.domain.example.com/r.git`) → 200 (the regex must not false-positive on subdomains — the `@` requirement does that job).
+
+## Testing & Quality
+- Integration: the cases above green (`uv run pytest tests/integration/test_admin_settings_api.py -v --no-cov`).
+- Coverage: **>90%** on `app/` (the gate must stay green — the guard helper must be covered by the 422 + pass cases).
+- Lint/types: `uv run ruff check . && uv run pyright`.
+
+## Completion Criteria
+- [ ] `uv run pytest tests/integration/test_admin_settings_api.py -v --no-cov` green, including: `docs_token` GET `is_set`/`value=null` (token text absent from the raw JSON), PUT store, blank PUT 422, DELETE reset; `docs_repo` embedded-creds 422 + clean/local/subdomain 200s.
+- [ ] The 422 detail names the Docs user / Docs token fields (asserted in the test, not just present).
+- [ ] `uv run pytest` green; ruff + pyright clean.
+- [ ] no behavior change in completed work (no other key's PUT path touched; the blank-secret guard at L273 byte-identical).
diff --git a/.agents/phases/complete/173_docs_push_creds_split/03_run_git_env_and_push.md b/.agents/phases/complete/173_docs_push_creds_split/03_run_git_env_and_push.md
new file mode 100644
index 0000000..0ef881c
--- /dev/null
+++ b/.agents/phases/complete/173_docs_push_creds_split/03_run_git_env_and_push.md
@@ -0,0 +1,47 @@
+# Task 03 — Credentials on the wire: `run_git(env=…)` + `push_document(user, token)`
+
+**Phase:** `173_docs_push_creds_split` · **Source:** C2/C5 (phase-locked) — credentials travel as `GIT_CURL_USERNAME` / `GIT_CURL_PASSWORD` env (never in the argv / process list); an empty token leaves the invocations byte-identical to today.
+**Story:** n/a
+
+## Objective
+The docs-push git sequence authenticates with the settings' user/token via git's documented HTTP credential environment, without the credential ever appearing in the command line, and without changing a single invocation when no token is set (C5).
+
+## Work
+1. `scripts/git_sync.py` — `run_git` (L320) gains one optional parameter:
+   ```python
+   def run_git(argv: list[str], cwd: Path, env: dict[str, str] | None = None) -> str:
+       …
+       proc = subprocess.run(
+           argv, cwd=cwd, capture_output=True, text=True, env=env
+       )
+   ```
+   `None` (the default, and the sync path's only usage) is byte-identical to today. **The subprocess env-replacement trap:** when `env` is a dict, it REPLACES the parent environment — the caller must build a complete environment (task 03's `docs_push` does the merge; a unit test pins `PATH` survival). Update the docstring: the `env` parameter is passed through verbatim; `None` = inherit.
+2. `app/core/docs_push.py` — `push_document` gains `user: str = ""` / `token: str = ""` (positional order: appended AFTER `commit_message`, so every existing call site keeps working; update the docstring with the C2 transport + the C5 no-token rule). At the top of the sequence:
+   ```python
+   git_env: dict[str, str] | None = None
+   if token.strip():
+       # C2: git's documented HTTP credential env — never in the argv.
+       # GIT_TERMINAL_PROMPT=0 fails fast instead of hanging the headless
+       # server on a credential prompt.
+       git_env = {
+           **os.environ,
+           "GIT_CURL_USERNAME": user,
+           "GIT_CURL_PASSWORD": token,
+           "GIT_TERMINAL_PROMPT": "0",
+       }
+   ```
+   Pass `env=git_env` to **every** `run_git` call in the sequence (clone, both fetches, `rev-parse` ×2, `branch --list`, checkout, add, commit, push — `rev-parse`/`branch` may take it too; uniformity over cleverness). The clean URL stays in the argv untouched. `DocsPushError` propagation is unchanged (the error still carries the full git stderr for logs; phase 84's `sanitize_error` on the API response stays as defense-in-depth). `GIT_CURL_*` is inert for `ssh://` / local-path remotes (accepted — the remote decides).
+3. `app/api/doc_drafts.py` — the push call site (L306–314) passes `user=settings.docs_user, token=settings.docs_token`. Nothing else changes (the 409 inert-switch on `docs_configured` stays repo-based — an empty token is a valid anonymous-push state, C5).
+4. `tests/unit/test_git_sync.py` (or the existing `run_git` test home) — (a) default: `run_git(["git", "version"], cwd)` → `subprocess.run` called with `env=None` (byte-identical to today); (b) an explicit `env={"A": "b"}` reaches `subprocess.run` verbatim.
+5. `tests/unit/test_docs_push.py` — (a) **no token** (default args) → every mocked `run_git` call gets `env=None` (the C5 byte-identity pin); (b) **token set** → every git step of a successful push gets an env with `GIT_CURL_USERNAME=user`, `GIT_CURL_PASSWORD=token`, `GIT_TERMINAL_PROMPT="0"`, **and** `PATH` present (the merge-over-`os.environ` pin — run with a controlled `os.environ` in the test); (c) whitespace-only token (`"  "`) → treated as empty (the `.strip()` rule) → `env=None`; (d) a failing step still raises `DocsPushError` with git's stderr — with and without credentials (the error path is credential-agnostic).
+
+## Testing & Quality
+- Unit: the cases above green (`uv run pytest tests/unit/test_git_sync.py tests/unit/test_docs_push.py -v --no-cov` — adjust file names to the existing homes if they differ).
+- Coverage: **>90%** on `app/` (the gate must stay green — the `token.strip()` branches are covered by 5a/5b/5c).
+- Lint/types: `uv run ruff check . && uv run pyright`.
+
+## Completion Criteria
+- [ ] `uv run pytest tests/unit/test_docs_push.py -v --no-cov` green: no-token `env=None` (all steps), token-set 3-var env merged over `os.environ` (`PATH` present, all steps), whitespace-only token = empty, `DocsPushError` propagation unchanged.
+- [ ] The sync path (`clone_or_pull`) is byte-identical (it never passes `env` — verify by reading: no `env=` at its `run_git` call sites).
+- [ ] `uv run pytest` green; ruff + pyright clean.
+- [ ] no behavior change in completed work (the git argv of an anonymous push is byte-identical to pre-phase; `sanitize_error` untouched).
diff --git a/.agents/phases/complete/173_docs_push_creds_split/04_legacy_creds_migration.md b/.agents/phases/complete/173_docs_push_creds_split/04_legacy_creds_migration.md
new file mode 100644
index 0000000..843def1
--- /dev/null
+++ b/.agents/phases/complete/173_docs_push_creds_split/04_legacy_creds_migration.md
@@ -0,0 +1,45 @@
+# Task 04 — The one-time startup migration of a legacy `://user:pass@` repo URL
+
+**Phase:** `173_docs_push_creds_split` · **Source:** C3 (phase-locked) — a legacy credentials-bearing `docs_repo` value (env or DB) is split once at startup into `app_settings` rows; the DB rows shadow the env; `.env` is never rewritten; idempotent; one INFO line.
+**Story:** n/a
+
+## Objective
+Production's existing `BOR_DOCS_REPO=https://ducoterra:<token>@gitea.…` keeps working (the push still authenticates) with zero operator action, while the effective value the settings page shows becomes the clean URL and the credentials live in `docs_user` / `docs_token` (masked). A second run is a no-op; owner-set values are never clobbered.
+
+## Work
+1. New module `app/core/settings_migrate.py`:
+   ```python
+   """One-time settings migrations (phase 173).
+
+   ``migrate_legacy_docs_creds`` splits a legacy ``://user:pass@``
+   ``docs_repo`` value into ``docs_repo`` (clean) + ``docs_user`` +
+   ``docs_token`` — DB rows that SHADOW the env (the settings model's
+   standing rule: the database wins over the environment). ``.env`` is
+   never read for writing or rewritten. Idempotent: it runs only while
+   no ``docs_token`` override exists, so owner-set values are never
+   clobbered. One INFO line when it acts (AGENTS rule 10).
+   """
+   ```
+   - `migrate_legacy_docs_creds() -> bool` — (1) read the `app_settings` overrides (via the overlay module's state — `load_overrides()` L93 or its backing read; use `reset_state_for_tests()` in tests); (2) the target value is the **effective** `docs_repo` (an override if present, else the env value — i.e. what `resolve_settings().docs_repo` resolves to, L239); (3) match `://([^/@:]+):([^@/]+)@` with BOTH groups non-empty — otherwise return `False` (no-op); (4) if a `docs_token` override already exists → `False` (no-op — never clobber); (5) otherwise write three rows (the overlay's existing write path — the same one the `PUT` route uses, or a direct `app_settings` insert if the overlay exposes none): `docs_repo` = the value with the `user:pass@` segment removed (e.g. `https://u:pass@host/r.git` → `https://host/r.git`), `docs_user` = user, `docs_token` = pass; log ONE INFO line: `settings: migrated embedded docs-push credentials out of docs_repo into docs_user/docs_token`; return `True`. A malformed `user:pass@` (empty user or pass) → `False`, no rows, no log (the legacy value stays as-is — the pre-phase behavior; nothing breaks, nothing half-migrates).
+2. `app/main.py` — `create_app()` (L98, the composition root): after the DB is available and BEFORE `return app`, call `settings_migrate.migrate_legacy_docs_creds()` ONCE (wrap in `try/except` so a migration hiccup logs a WARNING and never blocks startup — the app boots with the pre-phase behavior in that case; the migration is a convenience, not a dependency).
+3. `tests/unit/test_settings_migrate.py` — the four shapes (with the overlay state controlled via `reset_state_for_tests()` + a fake/monkeypatched override store — house style):
+   - (a) clean env URL, no overrides → `False`, no rows written;
+   - (b) legacy env `https://u:pass@host/r.git`, no overrides → `True`, three rows written (clean repo / `u` / `pass`), `resolve_settings()` resolves the clean URL from the DB;
+   - (c) legacy env + a `docs_token` override already present → `False`, the pre-existing rows are untouched (no clobber);
+   - (d) malformed `https://:@host/r.git` (empty user) → `False`, no rows, no log.
+   Plus: (e) the INFO line is emitted exactly once in (b) (caplog / log-capture, house style).
+4. `tests/integration/test_docs_push_migrate.py` — the end-to-end shape: seed env `BOR_DOCS_REPO=https://u:pass@host/r.git` (no DB rows) → run the migration (direct call, the `create_app()` wiring is covered by the unit seam) → `resolve_settings().docs_repo == "https://host/r.git"`, `docs_user == "u"`, `docs_token == "pass"` (all from DB overrides); a second call → `False` (idempotent); then `reset_state_for_tests()` for the next test.
+5. `.env.example` — the block comment added in task 01 (already covers this: "credentials in the repo URL are no longer supported — use BOR_DOCS_USER/BOR_DOCS_TOKEN"; the migration note: a legacy value is auto-split on startup into the new settings). No other file touched.
+
+## Testing & Quality
+- Unit: `tests/unit/test_settings_migrate.py` green (the 5 cases above).
+- Integration: `tests/integration/test_docs_push_migrate.py` green.
+- Coverage: **>90%** on `app/` (the gate must stay green — the no-op/act/clobber/malformed branches are all covered by 3a–3d; the `create_app()` try/except seam is covered by a unit test that monkeypatches the migration to raise).
+- Lint/types: `uv run ruff check . && uv run pyright`.
+
+## Completion Criteria
+- [ ] `uv run pytest tests/unit/test_settings_migrate.py tests/integration/test_docs_push_migrate.py -v --no-cov` green: the four shapes + the idempotency + the one-INFO-line pin.
+- [ ] `create_app()` calls the migration once, wrapped so a failure logs a WARNING and the app still boots (unit-asserted via the monkeypatched-raise seam).
+- [ ] After a (b)-shape migration, the settings API reports the clean `docs_repo` + `is_set=true` for `docs_token` with `value=null` (a quick curl or an integration assertion) — the leak is gone from the page.
+- [ ] `uv run pytest` green; ruff + pyright clean.
+- [ ] no behavior change in completed work (no pre-migration behavior touched; the sync path untouched).
diff --git a/.agents/phases/complete/173_docs_push_creds_split/05_e2e_docs_creds_masking.md b/.agents/phases/complete/173_docs_push_creds_split/05_e2e_docs_creds_masking.md
new file mode 100644
index 0000000..0299c62
--- /dev/null
+++ b/.agents/phases/complete/173_docs_push_creds_split/05_e2e_docs_creds_masking.md
@@ -0,0 +1,44 @@
+# Task 05 — The phase E2E suite + the full gates + the atomic commit
+
+**Phase:** `173_docs_push_creds_split` · **Source:** AGENTS rule 4 (one dedicated Playwright E2E suite per phase, run in isolation) + the test-gate protocol (AGENTS rules 8/9).
+**Story:** n/a
+
+## Objective
+`tests/e2e/test_docs_push_creds.py` proves the leak class is dead in the real UI — the `Docs token` row is write-only, masked, never pre-filled, and a saved token never appears anywhere in the page DOM — and the phase's full gate passes: 100% of the project suite, >90% `app/` coverage, ruff + pyright, the regression E2E set, one atomic `--no-gpg-sign` Conventional Commit, and the phase dir moves to `complete/`.
+
+## Work
+1. `tests/e2e/test_docs_push_creds.py` — the phase's dedicated Playwright suite (the phase-168 `test_admin_settings_panel.py` is the template for login + the settings panel; the mock-LLM default per A16 — the suite needs no LLM at all). Tests, in order:
+   - **rows render:** sign in as admin → Settings → the `Docs push` group shows a `Docs repo` text row (the clean URL, or the test-seed value), a `Docs user` text row, and a `Docs token` row that is write-only — its input is `type=password`, **not pre-filled** (value `""`, rendered `(stored)`-style per the phase-168 secret-row contract), and the token text is absent from the initial DOM.
+   - **save stays masked:** type a unique sentinel token (e.g. `e2e-sentinel-<uuid>` from the test) into the `Docs token` row → Save → the row re-renders masked; reload the page → the row is still masked, `is_set`-state visible, and the **sentinel text is absent from the entire page DOM** (the core assertion — `page.content()` must not contain the sentinel).
+   - **reset unsets:** Reset the `Docs token` row → the row returns to the not-set state (no `(stored)` marker).
+   - **the guard, UI-side:** type a credentials-bearing URL (`https://u:pass@e2e.invalid/o/r.git`) into `Docs repo` → Save → the 422 surfaces (the phase-168 error-display contract), the row keeps the previous value, and the page DOM never shows the typed URL's `pass` segment as a *saved* value (the input echoes what was typed before save — that is fine; the assertion is on the saved/persisted state after the failed save + reload).
+   - Seed/cleanup: the test manages its own `app_settings` rows via the admin API (or the test DB fixture the other settings E2Es use) — no state leaks between runs.
+2. **Regression set (run in isolation, house order):** `uv run pytest tests/e2e/test_admin_settings_panel.py tests/e2e/test_admin_settings_layout.py tests/e2e/test_response_to_docs.py -v --no-cov` — phase 168/171 (the settings panel) and phase 59 (the docs push) stay green.
+3. **Full gates:** `uv run pytest` (100% — every test in the project, pre-existing included) · `uv run pytest --cov=app --cov-report=term-missing` (>90% on `app/`) · `uv run ruff check . && uv run pyright`.
+4. **Docs & consistency pass (mandatory — AGENTS.md rule 5 / phase 00):** review `README.md` and `AGENTS.md` in their entirety against the project as it now stands; fix every inconsistency found — including pre-existing ones. At minimum: the README's docs-push section documents `BOR_DOCS_USER` / `BOR_DOCS_TOKEN`, states that credentials in the repo URL are no longer supported (the PUT 422 + the startup migration), and notes the token is masked (write-only) in the settings page/API.
+5. **Commit (AGENTS rule 8):** ONE atomic Conventional Commit, `--no-gpg-sign`, covering `app/`, `scripts/`, `.env.example`, `tests/`, the README fix, and this phase dir's move to `.agents/phases/complete/173_docs_push_creds_split/`. Message shape:
+   ```
+   feat(settings): split docs-push credentials (BOR_DOCS_USER/BOR_DOCS_TOKEN) out of the repo URL
+
+   - docs_token is write-only (masked in the page + API, llm_api_key-style); the
+     docs_repo PUT guard 422s on embedded credentials
+   - the push authenticates via GIT_CURL_USERNAME/GIT_CURL_PASSWORD env (never in
+     the argv); anonymous pushes are byte-identical to before
+   - a one-time startup migration splits a legacy ://user:pass@ env value into the
+     new settings (DB rows shadow the env; .env untouched; idempotent)
+
+   LLM-Generated: true
+   ```
+
+## Testing & Quality
+- E2E: `uv run pytest tests/e2e/test_docs_push_creds.py -v --no-cov` green **in isolation** (the phase's dedicated suite, AGENTS rule 4).
+- Full suite: `uv run pytest` 100% green; `app/` coverage **>90%**; ruff + pyright clean.
+- Regression: the phase 168/171/59 E2E set green in isolation.
+
+## Completion Criteria
+- [ ] `uv run pytest tests/e2e/test_docs_push_creds.py -v --no-cov` green in isolation: rows render, the token row is `type=password` + not pre-filled, save→reload keeps it masked with the sentinel **absent from the page DOM**, reset unsets, the 422 guard surfaces.
+- [ ] `uv run pytest tests/e2e/test_admin_settings_panel.py tests/e2e/test_admin_settings_layout.py tests/e2e/test_response_to_docs.py -v --no-cov` green in isolation.
+- [ ] `uv run pytest` 100% green; `uv run pytest --cov=app` >90% on `app/`; `uv run ruff check . && uv run pyright` clean.
+- [ ] `README.md` + `AGENTS.md` reviewed in full and consistent (the docs-push section documents the new vars + the guard + the migration).
+- [ ] One atomic `--no-gpg-sign` Conventional Commit; the phase dir moved to `.agents/phases/complete/173_docs_push_creds_split/`.
+- [ ] **Owner follow-up (noted, not code):** the exposed production Gitea token (seen in the 2026-10-10 audit) is rotated out-of-band; the migration makes its replacement the `docs_token` value.
diff --git a/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__00_phase.a1.err b/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__00_phase.a1.err
new file mode 100644
index 0000000..e69de29
diff --git a/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__00_phase.a1.md b/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__00_phase.a1.md
new file mode 100644
index 0000000..f8c35b0
--- /dev/null
+++ b/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__00_phase.a1.md
@@ -0,0 +1,17 @@
+All gates green. Final report:
+
+**Phase 173 — final verification pass (all tasks already complete in `complete/`)**
+
+- Verified the full implementation is in the working tree: `docs_user`/`docs_token` settings + catalogue rows (task 01), `docs_repo` PUT 422 guard + `docs_token` write-only pin (task 02), `run_git(env)` + `push_document(user, token)` credential env (task 03), `settings_migrate.py` wired into `create_app()` (task 04), E2E suite (task 05).
+- **Completion criteria:**
+  1. GET `/api/admin/settings` lists `docs_user` (plain) + `docs_token` (secret, `value=null`), token never in any body — ✅ `test_docs_token_is_write_only_masked_end_to_end` + E2E sentinel-absent-from-DOM
+  2. PUT `docs_repo` with `://user:pass@` → 422 naming the fields; clean URL passes — ✅ integration + E2E UI-side
+  3. Token set → `GIT_CURL_USERNAME`/`GIT_CURL_PASSWORD`/`GIT_TERMINAL_PROMPT=0` on every git step; empty → `env=None` — ✅ mocked-git unit tests
+  4. Legacy env split once at startup, idempotent, one INFO line, `.env` untouched — ✅ `test_settings_migrate.py` (4 shapes) + `test_docs_push_migrate.py`
+  5. Full suite green, coverage >90%, lint clean — ✅
+  6. E2E isolated: `test_docs_push_creds.py` 4/4; regression set (panel + layout + response_to_docs) 21/21 — ✅
+  7. Commit + phase move — harness's job (per instructions, not mine).
+  8. README/AGENTS consistent — ✅ (below)
+- Tests/lint: `uv run pytest` exit 0 (4112 passed) · `uv run pytest --cov=app --cov-report=term-missing` TOTAL 99% · `uv run ruff check .` clean · `uv run pyright` 0 errors
+- Docs: README.md (incl. Docs-push config section, guard/migration paragraph, `.env.example` block) and AGENTS.md verified consistent in full; fixed two stale docstrings in `app/config.py` + `app/core/settings_catalog.py` (`is_set` → the API's actual `has_value` field).
+- No live-infrastructure changes (no live step in this phase). No next pending phase — `todo/` held only 173.
diff --git a/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__00_phase.a1.md.status b/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__00_phase.a1.md.status
new file mode 100644
index 0000000..9766475
--- /dev/null
+++ b/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__00_phase.a1.md.status
@@ -0,0 +1 @@
+ok
diff --git a/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__00_phase.a1.validate b/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__00_phase.a1.validate
new file mode 100644
index 0000000..910357f
--- /dev/null
+++ b/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__00_phase.a1.validate
@@ -0,0 +1,136 @@
+........................................................................ [  1%]
+........................................................................ [  3%]
+........................................................................ [  5%]
+........................................................................ [  7%]
+........................................................................ [  8%]
+........................................................................ [ 10%]
+........................................................................ [ 12%]
+........................................................................ [ 14%]
+........................................................................ [ 15%]
+........................................................................ [ 17%]
+........................................................................ [ 19%]
+........................................................................ [ 21%]
+........................................................................ [ 22%]
+........................................................................ [ 24%]
+........................................................................ [ 26%]
+........................................................................ [ 28%]
+........................................................................ [ 29%]
+........................................................................ [ 31%]
+........................................................................ [ 33%]
+........................................................................ [ 35%]
+........................................................................ [ 36%]
+........................................................................ [ 38%]
+........................................................................ [ 40%]
+........................................................................ [ 42%]
+........................................................................ [ 43%]
+........................................................................ [ 45%]
+........................................................................ [ 47%]
+........................................................................ [ 49%]
+........................................................................ [ 50%]
+........................................................................ [ 52%]
+........................................................................ [ 54%]
+........................................................................ [ 56%]
+........................................................................ [ 57%]
+........................................................................ [ 59%]
+........................................................................ [ 61%]
+........................................................................ [ 63%]
+........................................................................ [ 64%]
+........................................................................ [ 66%]
+........................................................................ [ 68%]
+........................................................................ [ 70%]
+........................................................................ [ 71%]
+........................................................................ [ 73%]
+........................................................................ [ 75%]
+........................................................................ [ 77%]
+........................................................................ [ 78%]
+........................................................................ [ 80%]
+........................................................................ [ 82%]
+........................................................................ [ 84%]
+........................................................................ [ 85%]
+........................................................................ [ 87%]
+........................................................................ [ 89%]
+........................................................................ [ 91%]
+........................................................................ [ 92%]
+........................................................................ [ 94%]
+........................................................................ [ 96%]
+........................................................................ [ 98%]
+........................................................................ [ 99%]
+........                                                                 [100%]
+=============================== warnings summary ===============================
+.venv/lib/python3.13/site-packages/fastapi/testclient.py:1
+  /var/home/ducoterra/Projects/Personal/brain_of_reese/.venv/lib/python3.13/site-packages/fastapi/testclient.py:1: StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated; install `httpx2` instead.
+    from starlette.testclient import TestClient as TestClient  # noqa
+
+-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
+================================ tests coverage ================================
+_______________ coverage: platform linux, python 3.13.13-final-0 _______________
+
+Name                           Stmts   Miss  Cover
+--------------------------------------------------
+app/__init__.py                    1      0   100%
+app/api/__init__.py                0      0   100%
+app/api/admin_settings.py        114      0   100%
+app/api/auth.py                   52      0   100%
+app/api/chat.py                  280      1    99%
+app/api/chat_images.py            50      0   100%
+app/api/chats.py                 110      0   100%
+app/api/config.py                 13      0   100%
+app/api/doc_drafts.py             99      0   100%
+app/api/docs.py                  234      1    99%
+app/api/git_sources.py           259      0   100%
+app/api/health.py                 10      0   100%
+app/api/steering.py               42      0   100%
+app/api/suggestions.py            33      0   100%
+app/api/sync.py                  204      0   100%
+app/api/tokens.py                 40      0   100%
+app/api/ui_settings.py            55      0   100%
+app/config.py                    288      0   100%
+app/core/__init__.py               0      0   100%
+app/core/auth.py                  45      0   100%
+app/core/caching.py              124      0   100%
+app/core/compression.py           59      0   100%
+app/core/debugging.py             29      2    93%
+app/core/docs_push.py             43      0   100%
+app/core/errors.py                 5      0   100%
+app/core/http_cache.py            22      0   100%
+app/core/logging.py               13      0   100%
+app/core/rate_limit.py            44      0   100%
+app/core/response_budget.py       63      0   100%
+app/core/security_headers.py      20      0   100%
+app/core/settings_catalog.py      18      0   100%
+app/core/settings_migrate.py      32      0   100%
+app/core/settings_overlay.py     111      0   100%
+app/core/theming.py               38      0   100%
+app/core/tokens.py                44      0   100%
+app/db.py                         22      0   100%
+app/main.py                       91      0   100%
+app/models.py                    141      0   100%
+app/rag/__init__.py                0      0   100%
+app/rag/agent.py                 454      1    99%
+app/rag/archive_upload.py        134      0   100%
+app/rag/chunker.py               220      4    98%
+app/rag/doc_dates.py              18      0   100%
+app/rag/folder_summaries.py      134      0   100%
+app/rag/git_sources.py            77      0   100%
+app/rag/importer.py              841      4    99%
+app/rag/llm.py                   253      1    99%
+app/rag/md_images.py              63      0   100%
+app/rag/overview.py               78      0   100%
+app/rag/pdf.py                   192      0   100%
+app/rag/prompts.py               156      0   100%
+app/rag/retriever.py             252      3    99%
+app/rag/scaffolding.py            55      0   100%
+app/rag/source_removal.py         41      0   100%
+app/rag/sources_meta.py           16      0   100%
+app/rag/suggestions.py            27      0   100%
+app/rag/summarizer.py             58      0   100%
+app/schemas.py                   532      0   100%
+--------------------------------------------------
+TOTAL                           6449     17    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+WARNING: there is a new pyright version available (v1.1.411 -> v1.1.414).
+Please install the new version or set PYRIGHT_PYTHON_FORCE_VERSION to `latest`
+
+validation OK
diff --git a/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__01_config_and_catalog.a1.err b/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__01_config_and_catalog.a1.err
new file mode 100644
index 0000000..e69de29
diff --git a/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__01_config_and_catalog.a1.md b/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__01_config_and_catalog.a1.md
new file mode 100644
index 0000000..a20d9a9
--- /dev/null
+++ b/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__01_config_and_catalog.a1.md
@@ -0,0 +1,21 @@
+Task 01 complete.
+
+**Implemented**
+- `app/config.py`: `docs_user` / `docs_token` (default `""`, plain `str`, no validator) in the Docs push section, directly after `docs_repo`, house docstring style
+- `.env.example`: `# BOR_DOCS_USER=` / `# BOR_DOCS_TOKEN=` under `# BOR_DOCS_REPO=…` + comment line: credentials in the repo URL are no longer supported — use BOR_DOCS_USER/BOR_DOCS_TOKEN
+- `app/core/settings_catalog.py`: `docs_user` plain, `docs_token` `secret=True` in the `Docs push` group (landed in derived `SECRETS` automatically)
+- `tests/unit/test_settings_catalog.py`: exact-`SECRETS` pin updated with `docs_token`; house-style rows for both (group/label/derived-set membership)
+- `tests/unit/test_config.py`: defaults `""`, env overrides `alice`/`tok`, empty env stays `""` (no coercion — C5)
+
+**Verification (all green)**
+- `uv run pytest -k "docs" tests/unit/test_config.py tests/unit/test_settings_catalog.py -v --no-cov` → 18 passed
+- `uv run pytest --cov=app` → exit 0, full suite green (~4089 tests, 0 F/E), coverage 99% (>90%)
+- `uv run ruff check .` → all checks passed; `uv run pyright` → 0 errors
+- `grep -n "BOR_DOCS_USER" .env.example` → line 233, under `# BOR_DOCS_REPO=` (line 232, commented)
+- API check (in-process TestClient, admin login): `docs_user` plain `value=""`, `docs_token` `secret=true`, `masked=true`, `value=null`, `has_value=false`, group `Docs push`
+
+**Docs**: README.md Docs push table gains `BOR_DOCS_USER` / `BOR_DOCS_TOKEN` rows + "credentials in the repo URL are no longer supported" note on `BOR_DOCS_REPO`; no AGENTS.md impact (it documents no env vars).
+
+**Decisions**: updated the exact-`SECRETS` unit pin to include `docs_token` (required by the new `secret=True` entry; the pin is a load-bearing completeness gate). `docs_configured` + branch validator byte-identical; `frontend/` untouched.
+
+**Next pending task**: `.agents/phases/todo/173_docs_push_creds_split/02_api_masking_and_guards.md`
diff --git a/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__01_config_and_catalog.a1.md.status b/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__01_config_and_catalog.a1.md.status
new file mode 100644
index 0000000..9766475
--- /dev/null
+++ b/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__01_config_and_catalog.a1.md.status
@@ -0,0 +1 @@
+ok
diff --git a/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__01_config_and_catalog.a1.validate b/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__01_config_and_catalog.a1.validate
new file mode 100644
index 0000000..3e7539e
--- /dev/null
+++ b/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__01_config_and_catalog.a1.validate
@@ -0,0 +1,134 @@
+........................................................................ [  1%]
+........................................................................ [  3%]
+........................................................................ [  5%]
+........................................................................ [  7%]
+........................................................................ [  8%]
+........................................................................ [ 10%]
+........................................................................ [ 12%]
+........................................................................ [ 14%]
+........................................................................ [ 15%]
+........................................................................ [ 17%]
+........................................................................ [ 19%]
+........................................................................ [ 21%]
+........................................................................ [ 22%]
+........................................................................ [ 24%]
+........................................................................ [ 26%]
+........................................................................ [ 28%]
+........................................................................ [ 29%]
+........................................................................ [ 31%]
+........................................................................ [ 33%]
+........................................................................ [ 35%]
+........................................................................ [ 36%]
+........................................................................ [ 38%]
+........................................................................ [ 40%]
+........................................................................ [ 42%]
+........................................................................ [ 44%]
+........................................................................ [ 45%]
+........................................................................ [ 47%]
+........................................................................ [ 49%]
+........................................................................ [ 51%]
+........................................................................ [ 52%]
+........................................................................ [ 54%]
+........................................................................ [ 56%]
+........................................................................ [ 58%]
+........................................................................ [ 59%]
+........................................................................ [ 61%]
+........................................................................ [ 63%]
+........................................................................ [ 65%]
+........................................................................ [ 66%]
+........................................................................ [ 68%]
+........................................................................ [ 70%]
+........................................................................ [ 72%]
+........................................................................ [ 73%]
+........................................................................ [ 75%]
+........................................................................ [ 77%]
+........................................................................ [ 79%]
+........................................................................ [ 80%]
+........................................................................ [ 82%]
+........................................................................ [ 84%]
+........................................................................ [ 86%]
+........................................................................ [ 88%]
+........................................................................ [ 89%]
+........................................................................ [ 91%]
+........................................................................ [ 93%]
+........................................................................ [ 95%]
+........................................................................ [ 96%]
+........................................................................ [ 98%]
+.........................................................                [100%]
+=============================== warnings summary ===============================
+.venv/lib/python3.13/site-packages/fastapi/testclient.py:1
+  /var/home/ducoterra/Projects/Personal/brain_of_reese/.venv/lib/python3.13/site-packages/fastapi/testclient.py:1: StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated; install `httpx2` instead.
+    from starlette.testclient import TestClient as TestClient  # noqa
+
+-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
+================================ tests coverage ================================
+_______________ coverage: platform linux, python 3.13.13-final-0 _______________
+
+Name                           Stmts   Miss  Cover
+--------------------------------------------------
+app/__init__.py                    1      0   100%
+app/api/__init__.py                0      0   100%
+app/api/admin_settings.py        108      0   100%
+app/api/auth.py                   52      0   100%
+app/api/chat.py                  280      1    99%
+app/api/chat_images.py            50      0   100%
+app/api/chats.py                 110      0   100%
+app/api/config.py                 13      0   100%
+app/api/doc_drafts.py             99      0   100%
+app/api/docs.py                  234      1    99%
+app/api/git_sources.py           259      0   100%
+app/api/health.py                 10      0   100%
+app/api/steering.py               42      0   100%
+app/api/suggestions.py            33      0   100%
+app/api/sync.py                  204      0   100%
+app/api/tokens.py                 40      0   100%
+app/api/ui_settings.py            55      0   100%
+app/config.py                    288      0   100%
+app/core/__init__.py               0      0   100%
+app/core/auth.py                  45      0   100%
+app/core/caching.py              124      0   100%
+app/core/compression.py           59      0   100%
+app/core/debugging.py             29      2    93%
+app/core/docs_push.py             39      0   100%
+app/core/errors.py                 5      0   100%
+app/core/http_cache.py            22      0   100%
+app/core/logging.py               13      0   100%
+app/core/rate_limit.py            44      0   100%
+app/core/response_budget.py       63      0   100%
+app/core/security_headers.py      20      0   100%
+app/core/settings_catalog.py      18      0   100%
+app/core/settings_overlay.py     111      0   100%
+app/core/theming.py               38      0   100%
+app/core/tokens.py                44      0   100%
+app/db.py                         22      0   100%
+app/main.py                       86      0   100%
+app/models.py                    141      0   100%
+app/rag/__init__.py                0      0   100%
+app/rag/agent.py                 454      1    99%
+app/rag/archive_upload.py        134      0   100%
+app/rag/chunker.py               220      4    98%
+app/rag/doc_dates.py              18      0   100%
+app/rag/folder_summaries.py      134      0   100%
+app/rag/git_sources.py            77      0   100%
+app/rag/importer.py              841      4    99%
+app/rag/llm.py                   253      1    99%
+app/rag/md_images.py              63      0   100%
+app/rag/overview.py               78      0   100%
+app/rag/pdf.py                   192      0   100%
+app/rag/prompts.py               156      0   100%
+app/rag/retriever.py             252      3    99%
+app/rag/scaffolding.py            55      0   100%
+app/rag/source_removal.py         41      0   100%
+app/rag/sources_meta.py           16      0   100%
+app/rag/suggestions.py            27      0   100%
+app/rag/summarizer.py             58      0   100%
+app/schemas.py                   532      0   100%
+--------------------------------------------------
+TOTAL                           6402     17    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+WARNING: there is a new pyright version available (v1.1.411 -> v1.1.414).
+Please install the new version or set PYRIGHT_PYTHON_FORCE_VERSION to `latest`
+
+validation OK
diff --git a/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__02_api_masking_and_guards.a1.err b/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__02_api_masking_and_guards.a1.err
new file mode 100644
index 0000000..e69de29
diff --git a/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__02_api_masking_and_guards.a1.md b/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__02_api_masking_and_guards.a1.md
new file mode 100644
index 0000000..37197fd
--- /dev/null
+++ b/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__02_api_masking_and_guards.a1.md
@@ -0,0 +1,18 @@
+All gates green. Final report:
+
+**Implemented (task 02)**
+- `app/api/admin_settings.py`: `_EMBEDDED_CREDS` regex (`://<user>:<pass>@`) + `_refuse_embedded_credentials()` helper, called in the PUT route before the (byte-identical) blank-secret check; module/route docstrings updated
+- Integration pins in `test_admin_settings_api.py`: `docs_token` write-only contract (GET `secret=true`/`value=null`/`has_value=false`, PUT store + token text **absent from raw body**, blank PUT 422, DELETE reset) + `docs_repo` guard (embedded-creds 422 naming Docs user/token + nothing stored; clean https / local path / subdomain / `ssh://` all 200)
+- Unit pin in `tests/unit/test_admin_settings_api.py`: guard fires only for `docs_repo`, regex shapes (empty user/pass, subdomain, `git://` variant)
+- Fixed stale "75 items" doc counts → 78 in `admin_settings.py`, `schemas.py`, the integration test docstrings, and the E2E assert message
+
+**Results**
+- `uv run pytest tests/integration/test_admin_settings_api.py -v --no-cov` → 15 passed
+- `uv run pytest --cov=app --cov-report=term-missing` → **4092 passed, app/ 99%** (>90% gate)
+- `uv run ruff check .` → clean; `uv run pyright` → 0 errors
+
+**Docs**: README settings section gained the guard + legacy-migration line (vars/`.env.example` were task 01's); no AGENTS.md impact
+
+**Decisions**: tests assert the real wire field `has_value` (phase prose says "is_set" — docstring shorthand); base pinned via `monkeypatch.setenv("")` not `delenv` — `Settings` loads the repo `.env`, and the operator's local `.env` carries a live `BOR_DOCS_REPO` with embedded creds (the exact leak class); process env ranks above it.
+
+**Next pending task**: `03_run_git_env_and_push.md`
diff --git a/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__02_api_masking_and_guards.a1.md.status b/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__02_api_masking_and_guards.a1.md.status
new file mode 100644
index 0000000..9766475
--- /dev/null
+++ b/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__02_api_masking_and_guards.a1.md.status
@@ -0,0 +1 @@
+ok
diff --git a/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__02_api_masking_and_guards.a1.validate b/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__02_api_masking_and_guards.a1.validate
new file mode 100644
index 0000000..c1fe78b
--- /dev/null
+++ b/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__02_api_masking_and_guards.a1.validate
@@ -0,0 +1,134 @@
+........................................................................ [  1%]
+........................................................................ [  3%]
+........................................................................ [  5%]
+........................................................................ [  7%]
+........................................................................ [  8%]
+........................................................................ [ 10%]
+........................................................................ [ 12%]
+........................................................................ [ 14%]
+........................................................................ [ 15%]
+........................................................................ [ 17%]
+........................................................................ [ 19%]
+........................................................................ [ 21%]
+........................................................................ [ 22%]
+........................................................................ [ 24%]
+........................................................................ [ 26%]
+........................................................................ [ 28%]
+........................................................................ [ 29%]
+........................................................................ [ 31%]
+........................................................................ [ 33%]
+........................................................................ [ 35%]
+........................................................................ [ 36%]
+........................................................................ [ 38%]
+........................................................................ [ 40%]
+........................................................................ [ 42%]
+........................................................................ [ 43%]
+........................................................................ [ 45%]
+........................................................................ [ 47%]
+........................................................................ [ 49%]
+........................................................................ [ 51%]
+........................................................................ [ 52%]
+........................................................................ [ 54%]
+........................................................................ [ 56%]
+........................................................................ [ 58%]
+........................................................................ [ 59%]
+........................................................................ [ 61%]
+........................................................................ [ 63%]
+........................................................................ [ 65%]
+........................................................................ [ 66%]
+........................................................................ [ 68%]
+........................................................................ [ 70%]
+........................................................................ [ 72%]
+........................................................................ [ 73%]
+........................................................................ [ 75%]
+........................................................................ [ 77%]
+........................................................................ [ 79%]
+........................................................................ [ 80%]
+........................................................................ [ 82%]
+........................................................................ [ 84%]
+........................................................................ [ 86%]
+........................................................................ [ 87%]
+........................................................................ [ 89%]
+........................................................................ [ 91%]
+........................................................................ [ 93%]
+........................................................................ [ 95%]
+........................................................................ [ 96%]
+........................................................................ [ 98%]
+............................................................             [100%]
+=============================== warnings summary ===============================
+.venv/lib/python3.13/site-packages/fastapi/testclient.py:1
+  /var/home/ducoterra/Projects/Personal/brain_of_reese/.venv/lib/python3.13/site-packages/fastapi/testclient.py:1: StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated; install `httpx2` instead.
+    from starlette.testclient import TestClient as TestClient  # noqa
+
+-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
+================================ tests coverage ================================
+_______________ coverage: platform linux, python 3.13.13-final-0 _______________
+
+Name                           Stmts   Miss  Cover
+--------------------------------------------------
+app/__init__.py                    1      0   100%
+app/api/__init__.py                0      0   100%
+app/api/admin_settings.py        114      0   100%
+app/api/auth.py                   52      0   100%
+app/api/chat.py                  280      1    99%
+app/api/chat_images.py            50      0   100%
+app/api/chats.py                 110      0   100%
+app/api/config.py                 13      0   100%
+app/api/doc_drafts.py             99      0   100%
+app/api/docs.py                  234      1    99%
+app/api/git_sources.py           259      0   100%
+app/api/health.py                 10      0   100%
+app/api/steering.py               42      0   100%
+app/api/suggestions.py            33      0   100%
+app/api/sync.py                  204      0   100%
+app/api/tokens.py                 40      0   100%
+app/api/ui_settings.py            55      0   100%
+app/config.py                    288      0   100%
+app/core/__init__.py               0      0   100%
+app/core/auth.py                  45      0   100%
+app/core/caching.py              124      0   100%
+app/core/compression.py           59      0   100%
+app/core/debugging.py             29      2    93%
+app/core/docs_push.py             39      0   100%
+app/core/errors.py                 5      0   100%
+app/core/http_cache.py            22      0   100%
+app/core/logging.py               13      0   100%
+app/core/rate_limit.py            44      0   100%
+app/core/response_budget.py       63      0   100%
+app/core/security_headers.py      20      0   100%
+app/core/settings_catalog.py      18      0   100%
+app/core/settings_overlay.py     111      0   100%
+app/core/theming.py               38      0   100%
+app/core/tokens.py                44      0   100%
+app/db.py                         22      0   100%
+app/main.py                       86      0   100%
+app/models.py                    141      0   100%
+app/rag/__init__.py                0      0   100%
+app/rag/agent.py                 454      1    99%
+app/rag/archive_upload.py        134      0   100%
+app/rag/chunker.py               220      4    98%
+app/rag/doc_dates.py              18      0   100%
+app/rag/folder_summaries.py      134      0   100%
+app/rag/git_sources.py            77      0   100%
+app/rag/importer.py              841      4    99%
+app/rag/llm.py                   253      1    99%
+app/rag/md_images.py              63      0   100%
+app/rag/overview.py               78      0   100%
+app/rag/pdf.py                   192      0   100%
+app/rag/prompts.py               156      0   100%
+app/rag/retriever.py             252      3    99%
+app/rag/scaffolding.py            55      0   100%
+app/rag/source_removal.py         41      0   100%
+app/rag/sources_meta.py           16      0   100%
+app/rag/suggestions.py            27      0   100%
+app/rag/summarizer.py             58      0   100%
+app/schemas.py                   532      0   100%
+--------------------------------------------------
+TOTAL                           6408     17    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+WARNING: there is a new pyright version available (v1.1.411 -> v1.1.414).
+Please install the new version or set PYRIGHT_PYTHON_FORCE_VERSION to `latest`
+
+validation OK
diff --git a/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__03_run_git_env_and_push.a1.err b/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__03_run_git_env_and_push.a1.err
new file mode 100644
index 0000000..e69de29
diff --git a/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__03_run_git_env_and_push.a1.md b/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__03_run_git_env_and_push.a1.md
new file mode 100644
index 0000000..40a2e64
--- /dev/null
+++ b/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__03_run_git_env_and_push.a1.md
@@ -0,0 +1,18 @@
+All gates green. Final report:
+
+**Implemented**
+- `scripts/git_sync.py`: `run_git` gained optional `env: dict[str, str] | None = None`, passed verbatim to `subprocess.run`; docstring pins the env-replacement trap (`None` = inherit)
+- `app/core/docs_push.py`: `push_document(..., user="", token="")` — blank token → `env=None` (C5, byte-identical invocations); non-blank token → every git step (clone, fetch×2, rev-parse×2, branch probe, checkout, add, commit, push) gets `{**os.environ, GIT_CURL_USERNAME, GIT_CURL_PASSWORD, GIT_TERMINAL_PROMPT=0}` (C2); clean URL stays in argv; `DocsPushError` propagation unchanged
+- `app/api/doc_drafts.py`: call site passes `settings.docs_user` / `settings.docs_token`; 409 inert-switch and phase-84 `sanitize_error` untouched
+- Tests: `test_git_sync.py` (default `env=None` reaches subprocess; explicit env verbatim — same-object pin) + `test_docs_push.py` mocked-git section (full 10-step sequence: no-token all `env=None`; token → 3-var env merged over controlled `os.environ` with `PATH` present, credential absent from argv; whitespace-only token = empty; failing push raises `DocsPushError` with stderr, with/without creds)
+- Sync path verified by read: no `clone_or_pull` call site passes `env=`
+
+**Results**
+- `uv run pytest --cov=app --cov-report=term` → 4098 passed, 100% green; `app/` coverage 99% (>90% gate)
+- `uv run ruff check .` → clean; `uv run pyright` → 0 errors (fixed 43 initial type errors from the new test helper's dict typing)
+
+**Docs**: no doc impact this task — README + `.env.example` were already brought current by tasks 01/02 (new vars, "clean URL only" line)
+
+**Decisions**: mocked the `run_git` seam in `app.core.docs_push` (module's real-repo style kept; mocked section runs the full sequence including the swallowed branch-fetch-fail path); `GIT_TERMINAL_PROMPT=0` per D3
+
+**Next pending task**: `04_legacy_creds_migration.md`
diff --git a/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__03_run_git_env_and_push.a1.md.status b/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__03_run_git_env_and_push.a1.md.status
new file mode 100644
index 0000000..9766475
--- /dev/null
+++ b/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__03_run_git_env_and_push.a1.md.status
@@ -0,0 +1 @@
+ok
diff --git a/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__03_run_git_env_and_push.a1.validate b/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__03_run_git_env_and_push.a1.validate
new file mode 100644
index 0000000..138aae3
--- /dev/null
+++ b/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__03_run_git_env_and_push.a1.validate
@@ -0,0 +1,139 @@
+........................................................................ [  1%]
+........................................................................ [  3%]
+........................................................................ [  5%]
+........................................................................ [  7%]
+........................................................................ [  8%]
+........................................................................ [ 10%]
+........................................................................ [ 12%]
+........................................................................ [ 14%]
+........................................................................ [ 15%]
+........................................................................ [ 17%]
+........................................................................ [ 19%]
+........................................................................ [ 21%]
+........................................................................ [ 22%]
+........................................................................ [ 24%]
+........................................................................ [ 26%]
+........................................................................ [ 28%]
+........................................................................ [ 29%]
+........................................................................ [ 31%]
+........................................................................ [ 33%]
+........................................................................ [ 35%]
+........................................................................ [ 36%]
+........................................................................ [ 38%]
+........................................................................ [ 40%]
+........................................................................ [ 42%]
+........................................................................ [ 43%]
+........................................................................ [ 45%]
+........................................................................ [ 47%]
+........................................................................ [ 49%]
+........................................................................ [ 50%]
+........................................................................ [ 52%]
+........................................................................ [ 54%]
+........................................................................ [ 56%]
+........................................................................ [ 57%]
+........................................................................ [ 59%]
+........................................................................ [ 61%]
+........................................................................ [ 63%]
+........................................................................ [ 65%]
+........................................................................ [ 66%]
+........................................................................ [ 68%]
+........................................................................ [ 70%]
+........................................................................ [ 72%]
+........................................................................ [ 73%]
+........................................................................ [ 75%]
+........................................................................ [ 77%]
+........................................................................ [ 79%]
+........................................................................ [ 80%]
+........................................................................ [ 82%]
+........................................................................ [ 84%]
+........................................................................ [ 86%]
+........................................................................ [ 87%]
+........................................................................ [ 89%]
+........................................................................ [ 91%]
+........................................................................ [ 93%]
+........................................................................ [ 94%]
+........................................................................ [ 96%]
+........................................................................ [ 98%]
+..................................................................       [100%]
+=============================== warnings summary ===============================
+.venv/lib/python3.13/site-packages/fastapi/testclient.py:1
+  /var/home/ducoterra/Projects/Personal/brain_of_reese/.venv/lib/python3.13/site-packages/fastapi/testclient.py:1: StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated; install `httpx2` instead.
+    from starlette.testclient import TestClient as TestClient  # noqa
+
+-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
+================================ tests coverage ================================
+_______________ coverage: platform linux, python 3.13.13-final-0 _______________
+
+Name                           Stmts   Miss  Cover
+--------------------------------------------------
+app/__init__.py                    1      0   100%
+app/api/__init__.py                0      0   100%
+app/api/admin_settings.py        114      0   100%
+app/api/auth.py                   52      0   100%
+app/api/chat.py                  280      1    99%
+app/api/chat_images.py            50      0   100%
+app/api/chats.py                 110      0   100%
+app/api/config.py                 13      0   100%
+app/api/doc_drafts.py             99      0   100%
+app/api/docs.py                  234      1    99%
+app/api/git_sources.py           259      0   100%
+app/api/health.py                 10      0   100%
+app/api/steering.py               42      0   100%
+app/api/suggestions.py            33      0   100%
+app/api/sync.py                  204      0   100%
+app/api/tokens.py                 40      0   100%
+app/api/ui_settings.py            55      0   100%
+app/config.py                    288      0   100%
+app/core/__init__.py               0      0   100%
+app/core/auth.py                  45      0   100%
+app/core/caching.py              124      0   100%
+app/core/compression.py           59      0   100%
+app/core/debugging.py             29      2    93%
+app/core/docs_push.py             43      0   100%
+app/core/errors.py                 5      0   100%
+app/core/http_cache.py            22      0   100%
+app/core/logging.py               13      0   100%
+app/core/rate_limit.py            44      0   100%
+app/core/response_budget.py       63      0   100%
+app/core/security_headers.py      20      0   100%
+app/core/settings_catalog.py      18      0   100%
+app/core/settings_overlay.py     111      0   100%
+app/core/theming.py               38      0   100%
+app/core/tokens.py                44      0   100%
+app/db.py                         22      0   100%
+app/main.py                       86      0   100%
+app/models.py                    141      0   100%
+app/rag/__init__.py                0      0   100%
+app/rag/agent.py                 454      1    99%
+app/rag/archive_upload.py        134      0   100%
+app/rag/chunker.py               220      4    98%
+app/rag/doc_dates.py              18      0   100%
+app/rag/folder_summaries.py      134      0   100%
+app/rag/git_sources.py            77      0   100%
+app/rag/importer.py              841      4    99%
+app/rag/llm.py                   253      1    99%
+app/rag/md_images.py              63      0   100%
+app/rag/overview.py               78      0   100%
+app/rag/pdf.py                   192      0   100%
+app/rag/prompts.py               156      0   100%
+app/rag/retriever.py             252      3    99%
+app/rag/scaffolding.py            55      0   100%
+app/rag/source_removal.py         41      0   100%
+app/rag/sources_meta.py           16      0   100%
+app/rag/suggestions.py            27      0   100%
+app/rag/summarizer.py             58      0   100%
+app/schemas.py                   532      0   100%
+--------------------------------------------------
+TOTAL                           6412     17    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+/var/home/ducoterra/Projects/Personal/brain_of_reese/tests/unit/test_docs_push.py
+  /var/home/ducoterra/Projects/Personal/brain_of_reese/tests/unit/test_docs_push.py:286:12 - error: "__getitem__" method not defined on type "object" (reportIndexIssue)
+  /var/home/ducoterra/Projects/Personal/brain_of_reese/tests/unit/test_docs_push.py:314:16 - error: Operator "not in" not supported for types "Literal['alice']" and "object" (reportOperatorIssue)
+  /var/home/ducoterra/Projects/Personal/brain_of_reese/tests/unit/test_docs_push.py:315:16 - error: Operator "not in" not supported for types "Literal['s3cret']" and "object" (reportOperatorIssue)
+  /var/home/ducoterra/Projects/Personal/brain_of_reese/tests/unit/test_docs_push.py:317:12 - error: Operator "in" not supported for types "Literal['https://git.example.com/docs.git']" and "object" (reportOperatorIssue)
+4 errors, 0 warnings, 0 informations
+WARNING: there is a new pyright version available (v1.1.411 -> v1.1.414).
+Please install the new version or set PYRIGHT_PYTHON_FORCE_VERSION to `latest`
+
+validation FAILED (see output above)
diff --git a/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__03_run_git_env_and_push.a2.err b/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__03_run_git_env_and_push.a2.err
new file mode 100644
index 0000000..e69de29
diff --git a/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__03_run_git_env_and_push.a2.md b/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__03_run_git_env_and_push.a2.md
new file mode 100644
index 0000000..239de9e
--- /dev/null
+++ b/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__03_run_git_env_and_push.a2.md
@@ -0,0 +1,17 @@
+All gates green. Final report:
+
+**Fixed**
+- `tests/unit/test_docs_push.py`: replaced `list[dict[str, object]]` for recorded `run_git` calls with a `_GitCall` TypedDict (`argv: list[str]`, `cwd: Path`, `env: dict[str, str] | None`) — clears the 4 pyright errors (`__getitem__` on `object` at L286; `in`/`not in` with `object` argv at L314/315/317); also repaired a dropped docstring quote the harness run exposed
+- Root cause of the earlier "clean" read: my local pyright check grepped for ` error ` which never matches pyright's ` - error:` format — this run verified via the actual summary line
+
+**Results**
+- `uv run pytest --cov=app --cov-report=term` → 4098 passed, 100% green; `app/` coverage 99% (>90% gate)
+- `uv run ruff check .` → all checks passed
+- `uv run pyright` → 0 errors, 0 warnings (summary-line verified)
+- Targeted: `uv run pytest tests/unit/test_docs_push.py tests/unit/test_git_sync.py --no-cov` → 32 passed
+
+**Docs**: no doc impact this task — README/.env.example already brought current by tasks 01/02; AGENTS.md has no docs-push references
+
+**Decisions**: TypedDict keeps the existing `_fake_run_git` recording style (dicts, no new classes per call) while giving pyright precise field types; isinstance narrowing on `env` now resolves to `dict[str, str]`
+
+**Next pending task**: `04_legacy_creds_migration.md`
diff --git a/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__03_run_git_env_and_push.a2.md.status b/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__03_run_git_env_and_push.a2.md.status
new file mode 100644
index 0000000..9766475
--- /dev/null
+++ b/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__03_run_git_env_and_push.a2.md.status
@@ -0,0 +1 @@
+ok
diff --git a/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__03_run_git_env_and_push.a2.validate b/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__03_run_git_env_and_push.a2.validate
new file mode 100644
index 0000000..c182f05
--- /dev/null
+++ b/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__03_run_git_env_and_push.a2.validate
@@ -0,0 +1,134 @@
+........................................................................ [  1%]
+........................................................................ [  3%]
+........................................................................ [  5%]
+........................................................................ [  7%]
+........................................................................ [  8%]
+........................................................................ [ 10%]
+........................................................................ [ 12%]
+........................................................................ [ 14%]
+........................................................................ [ 15%]
+........................................................................ [ 17%]
+........................................................................ [ 19%]
+........................................................................ [ 21%]
+........................................................................ [ 22%]
+........................................................................ [ 24%]
+........................................................................ [ 26%]
+........................................................................ [ 28%]
+........................................................................ [ 29%]
+........................................................................ [ 31%]
+........................................................................ [ 33%]
+........................................................................ [ 35%]
+........................................................................ [ 36%]
+........................................................................ [ 38%]
+........................................................................ [ 40%]
+........................................................................ [ 42%]
+........................................................................ [ 43%]
+........................................................................ [ 45%]
+........................................................................ [ 47%]
+........................................................................ [ 49%]
+........................................................................ [ 50%]
+........................................................................ [ 52%]
+........................................................................ [ 54%]
+........................................................................ [ 56%]
+........................................................................ [ 57%]
+........................................................................ [ 59%]
+........................................................................ [ 61%]
+........................................................................ [ 63%]
+........................................................................ [ 65%]
+........................................................................ [ 66%]
+........................................................................ [ 68%]
+........................................................................ [ 70%]
+........................................................................ [ 72%]
+........................................................................ [ 73%]
+........................................................................ [ 75%]
+........................................................................ [ 77%]
+........................................................................ [ 79%]
+........................................................................ [ 80%]
+........................................................................ [ 82%]
+........................................................................ [ 84%]
+........................................................................ [ 86%]
+........................................................................ [ 87%]
+........................................................................ [ 89%]
+........................................................................ [ 91%]
+........................................................................ [ 93%]
+........................................................................ [ 94%]
+........................................................................ [ 96%]
+........................................................................ [ 98%]
+..................................................................       [100%]
+=============================== warnings summary ===============================
+.venv/lib/python3.13/site-packages/fastapi/testclient.py:1
+  /var/home/ducoterra/Projects/Personal/brain_of_reese/.venv/lib/python3.13/site-packages/fastapi/testclient.py:1: StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated; install `httpx2` instead.
+    from starlette.testclient import TestClient as TestClient  # noqa
+
+-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
+================================ tests coverage ================================
+_______________ coverage: platform linux, python 3.13.13-final-0 _______________
+
+Name                           Stmts   Miss  Cover
+--------------------------------------------------
+app/__init__.py                    1      0   100%
+app/api/__init__.py                0      0   100%
+app/api/admin_settings.py        114      0   100%
+app/api/auth.py                   52      0   100%
+app/api/chat.py                  280      1    99%
+app/api/chat_images.py            50      0   100%
+app/api/chats.py                 110      0   100%
+app/api/config.py                 13      0   100%
+app/api/doc_drafts.py             99      0   100%
+app/api/docs.py                  234      1    99%
+app/api/git_sources.py           259      0   100%
+app/api/health.py                 10      0   100%
+app/api/steering.py               42      0   100%
+app/api/suggestions.py            33      0   100%
+app/api/sync.py                  204      0   100%
+app/api/tokens.py                 40      0   100%
+app/api/ui_settings.py            55      0   100%
+app/config.py                    288      0   100%
+app/core/__init__.py               0      0   100%
+app/core/auth.py                  45      0   100%
+app/core/caching.py              124      0   100%
+app/core/compression.py           59      0   100%
+app/core/debugging.py             29      2    93%
+app/core/docs_push.py             43      0   100%
+app/core/errors.py                 5      0   100%
+app/core/http_cache.py            22      0   100%
+app/core/logging.py               13      0   100%
+app/core/rate_limit.py            44      0   100%
+app/core/response_budget.py       63      0   100%
+app/core/security_headers.py      20      0   100%
+app/core/settings_catalog.py      18      0   100%
+app/core/settings_overlay.py     111      0   100%
+app/core/theming.py               38      0   100%
+app/core/tokens.py                44      0   100%
+app/db.py                         22      0   100%
+app/main.py                       86      0   100%
+app/models.py                    141      0   100%
+app/rag/__init__.py                0      0   100%
+app/rag/agent.py                 454      1    99%
+app/rag/archive_upload.py        134      0   100%
+app/rag/chunker.py               220      4    98%
+app/rag/doc_dates.py              18      0   100%
+app/rag/folder_summaries.py      134      0   100%
+app/rag/git_sources.py            77      0   100%
+app/rag/importer.py              841      4    99%
+app/rag/llm.py                   253      1    99%
+app/rag/md_images.py              63      0   100%
+app/rag/overview.py               78      0   100%
+app/rag/pdf.py                   192      0   100%
+app/rag/prompts.py               156      0   100%
+app/rag/retriever.py             252      3    99%
+app/rag/scaffolding.py            55      0   100%
+app/rag/source_removal.py         41      0   100%
+app/rag/sources_meta.py           16      0   100%
+app/rag/suggestions.py            27      0   100%
+app/rag/summarizer.py             58      0   100%
+app/schemas.py                   532      0   100%
+--------------------------------------------------
+TOTAL                           6412     17    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+WARNING: there is a new pyright version available (v1.1.411 -> v1.1.414).
+Please install the new version or set PYRIGHT_PYTHON_FORCE_VERSION to `latest`
+
+validation OK
diff --git a/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__04_legacy_creds_migration.a1.err b/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__04_legacy_creds_migration.a1.err
new file mode 100644
index 0000000..e69de29
diff --git a/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__04_legacy_creds_migration.a1.md b/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__04_legacy_creds_migration.a1.md
new file mode 100644
index 0000000..ed04b24
--- /dev/null
+++ b/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__04_legacy_creds_migration.a1.md
@@ -0,0 +1,11 @@
+Everything is 100% green. 
+
+**Report — task 04 (legacy credentials migration, phase 173)**
+
+- **Implemented:** `app/core/settings_migrate.py` — `migrate_legacy_docs_creds()`: reads the effective `docs_repo` via the overlay (`resolve_settings`/`load_overrides`), matches `://<user>:<pass>@` (both groups non-empty), no-ops on clean/malformed values and on an existing `docs_token` override (idempotent, never clobbers), writes the three `app_settings` rows through the PUT route's own upsert (`.env` never touched, DB shadows env), one INFO line when it acts.
+- **Wired:** `create_app()` calls it once after the DB prime, wrapped in try/except — failure logs `settings migration failed (<Class>)` WARNING and never blocks boot.
+- **Tests:** `tests/unit/test_settings_migrate.py` (10 cases: clean env/DB no-op, malformed empty user/pass, subdomain false-positive guard, split + DB-shadowing, one-INFO-line pin, silent second run, clobber guard) + `create_app()` raise-seam test in `tests/unit/test_main.py` + `tests/integration/test_docs_push_migrate.py` (3 cases: end-to-end split/idempotency, settings-API masking pin with token text absent from the raw body, clean-env no-op).
+- **Results:** `uv run pytest` → 4112 passed (100% green); `uv run pytest --cov=app` → app/ **99%** (>90% gate; `settings_migrate.py` 100%); `uv run ruff check .` clean; `uv run pyright` 0 errors; unit + integration task files green in isolation.
+- **Docs:** `README.md` docs-push table gained the auto-migration line on `BOR_DOCS_REPO`; `.env.example` block gained the auto-split note. AGENTS.md: no impact.
+- **Decisions:** credential-strip keeps the `://` separator (`https://u:pass@host/r.git` → `https://host/r.git`); writes go through `app.db.SessionLocal` (the PUT route's write path — the overlay exposes none); migration checks the match before the token-override guard per the task's step order.
+- **Next pending task:** `05_e2e_docs_creds_masking.md` (phase's dedicated Playwright suite + regression set + full gates + atomic commit).
diff --git a/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__04_legacy_creds_migration.a1.md.status b/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__04_legacy_creds_migration.a1.md.status
new file mode 100644
index 0000000..9766475
--- /dev/null
+++ b/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__04_legacy_creds_migration.a1.md.status
@@ -0,0 +1 @@
+ok
diff --git a/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__04_legacy_creds_migration.a1.validate b/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__04_legacy_creds_migration.a1.validate
new file mode 100644
index 0000000..910357f
--- /dev/null
+++ b/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__04_legacy_creds_migration.a1.validate
@@ -0,0 +1,136 @@
+........................................................................ [  1%]
+........................................................................ [  3%]
+........................................................................ [  5%]
+........................................................................ [  7%]
+........................................................................ [  8%]
+........................................................................ [ 10%]
+........................................................................ [ 12%]
+........................................................................ [ 14%]
+........................................................................ [ 15%]
+........................................................................ [ 17%]
+........................................................................ [ 19%]
+........................................................................ [ 21%]
+........................................................................ [ 22%]
+........................................................................ [ 24%]
+........................................................................ [ 26%]
+........................................................................ [ 28%]
+........................................................................ [ 29%]
+........................................................................ [ 31%]
+........................................................................ [ 33%]
+........................................................................ [ 35%]
+........................................................................ [ 36%]
+........................................................................ [ 38%]
+........................................................................ [ 40%]
+........................................................................ [ 42%]
+........................................................................ [ 43%]
+........................................................................ [ 45%]
+........................................................................ [ 47%]
+........................................................................ [ 49%]
+........................................................................ [ 50%]
+........................................................................ [ 52%]
+........................................................................ [ 54%]
+........................................................................ [ 56%]
+........................................................................ [ 57%]
+........................................................................ [ 59%]
+........................................................................ [ 61%]
+........................................................................ [ 63%]
+........................................................................ [ 64%]
+........................................................................ [ 66%]
+........................................................................ [ 68%]
+........................................................................ [ 70%]
+........................................................................ [ 71%]
+........................................................................ [ 73%]
+........................................................................ [ 75%]
+........................................................................ [ 77%]
+........................................................................ [ 78%]
+........................................................................ [ 80%]
+........................................................................ [ 82%]
+........................................................................ [ 84%]
+........................................................................ [ 85%]
+........................................................................ [ 87%]
+........................................................................ [ 89%]
+........................................................................ [ 91%]
+........................................................................ [ 92%]
+........................................................................ [ 94%]
+........................................................................ [ 96%]
+........................................................................ [ 98%]
+........................................................................ [ 99%]
+........                                                                 [100%]
+=============================== warnings summary ===============================
+.venv/lib/python3.13/site-packages/fastapi/testclient.py:1
+  /var/home/ducoterra/Projects/Personal/brain_of_reese/.venv/lib/python3.13/site-packages/fastapi/testclient.py:1: StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated; install `httpx2` instead.
+    from starlette.testclient import TestClient as TestClient  # noqa
+
+-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
+================================ tests coverage ================================
+_______________ coverage: platform linux, python 3.13.13-final-0 _______________
+
+Name                           Stmts   Miss  Cover
+--------------------------------------------------
+app/__init__.py                    1      0   100%
+app/api/__init__.py                0      0   100%
+app/api/admin_settings.py        114      0   100%
+app/api/auth.py                   52      0   100%
+app/api/chat.py                  280      1    99%
+app/api/chat_images.py            50      0   100%
+app/api/chats.py                 110      0   100%
+app/api/config.py                 13      0   100%
+app/api/doc_drafts.py             99      0   100%
+app/api/docs.py                  234      1    99%
+app/api/git_sources.py           259      0   100%
+app/api/health.py                 10      0   100%
+app/api/steering.py               42      0   100%
+app/api/suggestions.py            33      0   100%
+app/api/sync.py                  204      0   100%
+app/api/tokens.py                 40      0   100%
+app/api/ui_settings.py            55      0   100%
+app/config.py                    288      0   100%
+app/core/__init__.py               0      0   100%
+app/core/auth.py                  45      0   100%
+app/core/caching.py              124      0   100%
+app/core/compression.py           59      0   100%
+app/core/debugging.py             29      2    93%
+app/core/docs_push.py             43      0   100%
+app/core/errors.py                 5      0   100%
+app/core/http_cache.py            22      0   100%
+app/core/logging.py               13      0   100%
+app/core/rate_limit.py            44      0   100%
+app/core/response_budget.py       63      0   100%
+app/core/security_headers.py      20      0   100%
+app/core/settings_catalog.py      18      0   100%
+app/core/settings_migrate.py      32      0   100%
+app/core/settings_overlay.py     111      0   100%
+app/core/theming.py               38      0   100%
+app/core/tokens.py                44      0   100%
+app/db.py                         22      0   100%
+app/main.py                       91      0   100%
+app/models.py                    141      0   100%
+app/rag/__init__.py                0      0   100%
+app/rag/agent.py                 454      1    99%
+app/rag/archive_upload.py        134      0   100%
+app/rag/chunker.py               220      4    98%
+app/rag/doc_dates.py              18      0   100%
+app/rag/folder_summaries.py      134      0   100%
+app/rag/git_sources.py            77      0   100%
+app/rag/importer.py              841      4    99%
+app/rag/llm.py                   253      1    99%
+app/rag/md_images.py              63      0   100%
+app/rag/overview.py               78      0   100%
+app/rag/pdf.py                   192      0   100%
+app/rag/prompts.py               156      0   100%
+app/rag/retriever.py             252      3    99%
+app/rag/scaffolding.py            55      0   100%
+app/rag/source_removal.py         41      0   100%
+app/rag/sources_meta.py           16      0   100%
+app/rag/suggestions.py            27      0   100%
+app/rag/summarizer.py             58      0   100%
+app/schemas.py                   532      0   100%
+--------------------------------------------------
+TOTAL                           6449     17    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+WARNING: there is a new pyright version available (v1.1.411 -> v1.1.414).
+Please install the new version or set PYRIGHT_PYTHON_FORCE_VERSION to `latest`
+
+validation OK
diff --git a/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__05_e2e_docs_creds_masking.a1.err b/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__05_e2e_docs_creds_masking.a1.err
new file mode 100644
index 0000000..e69de29
diff --git a/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__05_e2e_docs_creds_masking.a1.md b/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__05_e2e_docs_creds_masking.a1.md
new file mode 100644
index 0000000..9960787
--- /dev/null
+++ b/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__05_e2e_docs_creds_masking.a1.md
@@ -0,0 +1,19 @@
+All gates green. Task 05 complete — final report:
+
+**Implemented**
+- `tests/e2e/test_docs_push_creds.py` — the phase's dedicated Playwright suite (4 tests, own port 8190, phase-168 house patterns: overlay opt-in, per-test DB isolation, `.env` mtime guard, no-LLM): rows render with `Docs token` as `type=password`/not pre-filled/`(stored)`-placeholder with the seeded token absent from DOM+HTML+API; save→reload keeps it masked with the uuid sentinel **absent from `page.content()`**; Reset unsets (disabled Reset + env badge + API `has_value=false`); the 422 guard surfaces (role=alert naming `docs_repo` + the Docs user/Docs token fields), the row keeps the previous clean value, and the typed `u:pass@` URL never persists.
+- Fixed a pre-existing defect found by the regression pass: `test_admin_settings_panel.py::test_clear_all_overrides` raced the post-clear re-GET (status line lands before the settled render) — the bare `count() == 0` snapshot is now a polling `expect(...).to_have_count(0)` (contract unchanged).
+
+**Test / lint / coverage (all green)**
+- `uv run pytest tests/e2e/test_docs_push_creds.py -v --no-cov` → 4 passed (twice, in isolation)
+- `uv run pytest tests/e2e/test_admin_settings_panel.py tests/e2e/test_admin_settings_layout.py tests/e2e/test_response_to_docs.py -v --no-cov` → 21 passed
+- `uv run pytest --cov=app --cov-report=term-missing` → 4112 passed, 0 failed; `app/` TOTAL 99% (>90% gate)
+- `uv run ruff check . && uv run pyright` → clean (0 errors)
+
+**Docs**
+- README: full review — docs-push section (new vars + guard + migration) and the overlay section verified accurate (fixed by this phase's earlier tasks); config-reference defaults spot-checked vs `config.py`; all 78 `.env.example` vars documented; no stale cred-bearing-URL examples. AGENTS.md: reviewed in full — consistent, no change needed.
+
+**Decisions / deviations**
+- Commit + phase-dir move: left to the harness per harness rules (no git index/history commands). Owner follow-up (production token rotation) is noted, not code.
+
+**Next pending task:** none in `173_docs_push_creds_split` — task 05 was the phase's final task.
diff --git a/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__05_e2e_docs_creds_masking.a1.md.status b/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__05_e2e_docs_creds_masking.a1.md.status
new file mode 100644
index 0000000..9766475
--- /dev/null
+++ b/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__05_e2e_docs_creds_masking.a1.md.status
@@ -0,0 +1 @@
+ok
diff --git a/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__05_e2e_docs_creds_masking.a1.validate b/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__05_e2e_docs_creds_masking.a1.validate
new file mode 100644
index 0000000..910357f
--- /dev/null
+++ b/.agents/reports/173_docs_push_creds_split/173_docs_push_creds_split__05_e2e_docs_creds_masking.a1.validate
@@ -0,0 +1,136 @@
+........................................................................ [  1%]
+........................................................................ [  3%]
+........................................................................ [  5%]
+........................................................................ [  7%]
+........................................................................ [  8%]
+........................................................................ [ 10%]
+........................................................................ [ 12%]
+........................................................................ [ 14%]
+........................................................................ [ 15%]
+........................................................................ [ 17%]
+........................................................................ [ 19%]
+........................................................................ [ 21%]
+........................................................................ [ 22%]
+........................................................................ [ 24%]
+........................................................................ [ 26%]
+........................................................................ [ 28%]
+........................................................................ [ 29%]
+........................................................................ [ 31%]
+........................................................................ [ 33%]
+........................................................................ [ 35%]
+........................................................................ [ 36%]
+........................................................................ [ 38%]
+........................................................................ [ 40%]
+........................................................................ [ 42%]
+........................................................................ [ 43%]
+........................................................................ [ 45%]
+........................................................................ [ 47%]
+........................................................................ [ 49%]
+........................................................................ [ 50%]
+........................................................................ [ 52%]
+........................................................................ [ 54%]
+........................................................................ [ 56%]
+........................................................................ [ 57%]
+........................................................................ [ 59%]
+........................................................................ [ 61%]
+........................................................................ [ 63%]
+........................................................................ [ 64%]
+........................................................................ [ 66%]
+........................................................................ [ 68%]
+........................................................................ [ 70%]
+........................................................................ [ 71%]
+........................................................................ [ 73%]
+........................................................................ [ 75%]
+........................................................................ [ 77%]
+........................................................................ [ 78%]
+........................................................................ [ 80%]
+........................................................................ [ 82%]
+........................................................................ [ 84%]
+........................................................................ [ 85%]
+........................................................................ [ 87%]
+........................................................................ [ 89%]
+........................................................................ [ 91%]
+........................................................................ [ 92%]
+........................................................................ [ 94%]
+........................................................................ [ 96%]
+........................................................................ [ 98%]
+........................................................................ [ 99%]
+........                                                                 [100%]
+=============================== warnings summary ===============================
+.venv/lib/python3.13/site-packages/fastapi/testclient.py:1
+  /var/home/ducoterra/Projects/Personal/brain_of_reese/.venv/lib/python3.13/site-packages/fastapi/testclient.py:1: StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated; install `httpx2` instead.
+    from starlette.testclient import TestClient as TestClient  # noqa
+
+-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
+================================ tests coverage ================================
+_______________ coverage: platform linux, python 3.13.13-final-0 _______________
+
+Name                           Stmts   Miss  Cover
+--------------------------------------------------
+app/__init__.py                    1      0   100%
+app/api/__init__.py                0      0   100%
+app/api/admin_settings.py        114      0   100%
+app/api/auth.py                   52      0   100%
+app/api/chat.py                  280      1    99%
+app/api/chat_images.py            50      0   100%
+app/api/chats.py                 110      0   100%
+app/api/config.py                 13      0   100%
+app/api/doc_drafts.py             99      0   100%
+app/api/docs.py                  234      1    99%
+app/api/git_sources.py           259      0   100%
+app/api/health.py                 10      0   100%
+app/api/steering.py               42      0   100%
+app/api/suggestions.py            33      0   100%
+app/api/sync.py                  204      0   100%
+app/api/tokens.py                 40      0   100%
+app/api/ui_settings.py            55      0   100%
+app/config.py                    288      0   100%
+app/core/__init__.py               0      0   100%
+app/core/auth.py                  45      0   100%
+app/core/caching.py              124      0   100%
+app/core/compression.py           59      0   100%
+app/core/debugging.py             29      2    93%
+app/core/docs_push.py             43      0   100%
+app/core/errors.py                 5      0   100%
+app/core/http_cache.py            22      0   100%
+app/core/logging.py               13      0   100%
+app/core/rate_limit.py            44      0   100%
+app/core/response_budget.py       63      0   100%
+app/core/security_headers.py      20      0   100%
+app/core/settings_catalog.py      18      0   100%
+app/core/settings_migrate.py      32      0   100%
+app/core/settings_overlay.py     111      0   100%
+app/core/theming.py               38      0   100%
+app/core/tokens.py                44      0   100%
+app/db.py                         22      0   100%
+app/main.py                       91      0   100%
+app/models.py                    141      0   100%
+app/rag/__init__.py                0      0   100%
+app/rag/agent.py                 454      1    99%
+app/rag/archive_upload.py        134      0   100%
+app/rag/chunker.py               220      4    98%
+app/rag/doc_dates.py              18      0   100%
+app/rag/folder_summaries.py      134      0   100%
+app/rag/git_sources.py            77      0   100%
+app/rag/importer.py              841      4    99%
+app/rag/llm.py                   253      1    99%
+app/rag/md_images.py              63      0   100%
+app/rag/overview.py               78      0   100%
+app/rag/pdf.py                   192      0   100%
+app/rag/prompts.py               156      0   100%
+app/rag/retriever.py             252      3    99%
+app/rag/scaffolding.py            55      0   100%
+app/rag/source_removal.py         41      0   100%
+app/rag/sources_meta.py           16      0   100%
+app/rag/suggestions.py            27      0   100%
+app/rag/summarizer.py             58      0   100%
+app/schemas.py                   532      0   100%
+--------------------------------------------------
+TOTAL                           6449     17    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+WARNING: there is a new pyright version available (v1.1.411 -> v1.1.414).
+Please install the new version or set PYRIGHT_PYTHON_FORCE_VERSION to `latest`
+
+validation OK
diff --git a/.env.example b/.env.example
index 1996c2f..d622d54 100644
--- a/.env.example
+++ b/.env.example
@@ -227,8 +227,13 @@ BOR_IMPORT_EXTENSIONS=md,markdown,txt,yaml,yml,json,py,container,network,volume,
 # The git repo chat answers can be committed to — any remote (URL or
 # local path). While empty, the "Save as doc" action is hidden and the
 # push endpoint 409s. Commits land on BOR_DOCS_BRANCH (push --ff-only);
-# open the PR yourself.
+# open the PR yourself. Credentials in the repo URL are no longer
+# supported (phase 173) — use BOR_DOCS_USER/BOR_DOCS_TOKEN (a legacy
+# value is auto-split into them on startup, one-time, idempotent —
+# this file is never rewritten).
 # BOR_DOCS_REPO=/path/to/docs-repo
+# BOR_DOCS_USER=
+# BOR_DOCS_TOKEN=
 # BOR_DOCS_BRANCH=bor-docs
 # BOR_DOCS_BASE_BRANCH=main
 # BOR_DOCS_WORK_DIR=~/bor-docs
diff --git a/README.md b/README.md
index 205965c..23e1696 100644
--- a/README.md
+++ b/README.md
@@ -1118,7 +1118,11 @@ Admins read/write the overrides through the admin-only
 `/api/admin/settings` routes (GET the catalogue, PUT `/{key}` set one
 value, DELETE `/{key}` reset one, DELETE all clear everything);
 secrets are write-only there (the response reports `has_value`,
-never the plaintext).
+never the plaintext). A `docs_repo` PUT with embedded credentials
+(`://user:pass@` — the phase-173 leak class) is refused with a 422
+pointing at the `docs_user` / `docs_token` fields; a legacy `.env`
+value of that shape is split into those two settings once at
+startup (the DB rows shadow the env, `.env` is never rewritten).
 
 ### App & branding
 
@@ -1237,7 +1241,9 @@ never the plaintext).
 
 | Env | Default | Meaning |
 |-----|---------|---------|
-| `BOR_DOCS_REPO` | — (empty) | The git repo chat answers can be committed to (URL or local path); while empty "Save as doc" is hidden and the push endpoint 409s |
+| `BOR_DOCS_REPO` | — (empty) | The git repo chat answers can be committed to (URL or local path); while empty "Save as doc" is hidden and the push endpoint 409s — a **clean URL only**: credentials in the repo URL are no longer supported (phase 173), use `BOR_DOCS_USER` / `BOR_DOCS_TOKEN`. A legacy `://user:pass@` value (env or a saved override) is auto-split on startup into those settings, one-time and idempotent — the `.env` file is never rewritten |
+| `BOR_DOCS_USER` | — (empty) | The docs-push remote's username; travels to git as the `GIT_CURL_USERNAME` environment variable (never in the command line); empty = the push is anonymous (phase 173) |
+| `BOR_DOCS_TOKEN` | — (empty) | The docs-push remote's token — **write-only**: the settings API reports `is_set` and never the value, and the admin panel renders it masked; travels to git as `GIT_CURL_PASSWORD` (with `GIT_TERMINAL_PROMPT=0`); empty = the credential env is not set at all (phase 173) |
 | `BOR_DOCS_BRANCH` | `bor-docs` | Branch pushes land on (`git push --ff-only` — you open the PR yourself) |
 | `BOR_DOCS_BASE_BRANCH` | `main` | Branch each push is cut fresh from |
 | `BOR_DOCS_WORK_DIR` | `~/bor-docs` | Where `BOR_DOCS_REPO` is checked out on the server |
diff --git a/app/api/admin_settings.py b/app/api/admin_settings.py
index fb7c51a..2089a4c 100644
--- a/app/api/admin_settings.py
+++ b/app/api/admin_settings.py
@@ -24,10 +24,13 @@ Routes (under ``/api`` via the ``main`` registration):
   (e.g. ``lexical_support_floor`` above a DB-overridden
   ``relevance_threshold``) is a 422 that names the field and stores
   NOTHING. Unknown key → 404; a non-overridable key (LOCKED A3) → 422
-  naming the env var; a blank value for a secret → 422 (an empty API
-  key / session secret is a self-lockout; ``DELETE`` is the explicit
-  clear). A successful write commits, calls ``invalidate_settings()``
-  (task 03 makes it live — no restart) and returns the refreshed item.
+  naming the env var; a ``docs_repo`` value with embedded credentials
+  (``://user:pass@``, the phase-173 leak class) → 422 pointing at the
+  ``docs_user`` / ``docs_token`` fields (C4); a blank value for a
+  secret → 422 (an empty API key / session secret is a self-lockout;
+  ``DELETE`` is the explicit clear). A successful write commits, calls
+  ``invalidate_settings()`` (task 03 makes it live — no restart) and
+  returns the refreshed item.
 * ``DELETE /api/admin/settings/{key}`` — reset to env: deletes the row
   (idempotent — deleting an absent key is a success, not a 404),
   invalidates, returns the item with ``source="env"``/``"default"``.
@@ -51,6 +54,7 @@ from __future__ import annotations
 import json
 import logging
 import os
+import re
 from typing import Any, Literal, get_origin
 
 from fastapi import APIRouter, Depends, HTTPException
@@ -210,11 +214,37 @@ def _validate_candidate(candidate: dict[str, str]) -> None:
         ) from exc
 
 
+#: A git URL with embedded credentials (``://<user>:<pass>@``) — the
+#: phase-173 leak class. Refused for ``docs_repo`` on the way in:
+#: the credentials belong in ``docs_user`` / ``docs_token`` (C4).
+_EMBEDDED_CREDS = re.compile(r"://[^/@:]+:[^@/]+@")
+
+
+def _refuse_embedded_credentials(key: str, value: str) -> None:
+    """The phase-173 guard (C4): a ``docs_repo`` PUT whose value embeds
+    ``://<user>:<pass>@`` is a 422 that names the replacement — the
+    leak cannot be re-created from the UI. Only ``docs_repo`` is
+    guarded: ``ssh://`` URLs, local paths and clean ``https://`` URLs
+    pass untouched (a ``://user:pass@`` *subdomain* does not match —
+    the trailing ``@`` requirement does that job). A legacy ``.env``
+    value with embedded credentials is NOT a PUT — the task-04 startup
+    migration handles that path."""
+    if key == "docs_repo" and _EMBEDDED_CREDS.search(value):
+        raise HTTPException(
+            status_code=422,
+            detail=(
+                "docs_repo must not contain embedded credentials — "
+                "keep the URL clean and set them in the Docs user / "
+                "Docs token fields instead"
+            ),
+        )
+
+
 @router.get("", response_model=AdminSettingsOut)
 def get_catalogue(
     db: Session = Depends(get_db),  # noqa: B008
 ) -> AdminSettingsOut:
-    """The whole catalogue (75 items, ``GROUPS`` order — the stable
+    """The whole catalogue (78 items, ``GROUPS`` order — the stable
     order the E2E pins against).
 
     Reads the table once, resolves the effective ``Settings`` through
@@ -222,7 +252,7 @@ def get_catalogue(
     emits one item per field. GETs log nothing here: the phase-167
     ``ResponseBudgetMiddleware`` already writes the
     ``api method=… bytes=…`` line, and the whole catalogue must stay
-    under ``BOR_LOG_LARGE_RESPONSE_BYTES``' INFO bar (75 items ≈ 20 KB
+    under ``BOR_LOG_LARGE_RESPONSE_BYTES``' INFO bar (78 items ≈ 20 KB
     — verified in task 06 with the audit script).
     """
     rows = _rows(db)
@@ -253,14 +283,17 @@ def set_value(
     form, D1), make it live (``invalidate_settings()`` — task 03) and
     return the refreshed item.
 
-    The write path (LOCKED A5, A3, A4): unknown key → 404; a
+    The write path (LOCKED A5, A3, A4, C4): unknown key → 404; a
     non-overridable key → 422 naming the env var (A3: the engine is
     built from ``database_url`` — an override is a chicken-and-egg
     brick; ``chunks.embedding`` is fixed at ``embedding_dim`` by A6,
-    so a dim override would corrupt retrieval); a blank value for a
-    secret → 422 (a self-lockout; ``DELETE`` is the explicit clear);
-    then the FULL candidate set is validated before anything is
-    stored (a 422 names the field and writes nothing).
+    so a dim override would corrupt retrieval); a ``docs_repo`` value
+    with embedded credentials → 422 pointing at the ``docs_user`` /
+    ``docs_token`` fields (C4 — the phase-173 leak class, refused on
+    the way in); a blank value for a secret → 422 (a self-lockout;
+    ``DELETE`` is the explicit clear); then the FULL candidate set is
+    validated before anything is stored (a 422 names the field and
+    writes nothing).
     """
     meta = CATALOG.get(key)
     if meta is None:
@@ -270,6 +303,7 @@ def set_value(
             status_code=422,
             detail=f"{env_var(key)} is not settable from the database",
         )
+    _refuse_embedded_credentials(key, payload.value)
     if meta.secret and not payload.value.strip():
         raise HTTPException(
             status_code=422,
@@ -337,7 +371,7 @@ def reset_value(
 @router.delete("", response_model=AdminSettingsCleared)
 def reset_all(db: Session = Depends(get_db)) -> AdminSettingsCleared:  # noqa: B008
     """The panel's "Clear all overrides": delete every row (the env
-    values win again for all 75 settings), invalidate (task 03) and
+    values win again for all 78 settings), invalidate (task 03) and
     report how many rows went."""
     result = db.execute(delete(AppSetting).returning(AppSetting.key))
     db.commit()
diff --git a/app/api/doc_drafts.py b/app/api/doc_drafts.py
index e61df84..e5e5710 100644
--- a/app/api/doc_drafts.py
+++ b/app/api/doc_drafts.py
@@ -310,6 +310,11 @@ def push_doc_draft(
             rel_path=path,
             content=row.body,
             commit_message=f"docs: {row.title}",
+            # Phase 173 (C2/C5): the docs-push credentials travel as git's
+            # GIT_CURL_* env (never in the argv); an empty token leaves the
+            # invocations byte-identical to the pre-phase anonymous push.
+            user=settings.docs_user,
+            token=settings.docs_token,
         )
     except DocsPushError as exc:
         # Phase 84 (SEC-08): git's stderr may echo the remote URL with
diff --git a/app/config.py b/app/config.py
index 04f203a..1c3cd91 100644
--- a/app/config.py
+++ b/app/config.py
@@ -537,6 +537,19 @@ class Settings(BaseSettings):
     #: hidden and the push endpoint 409s (the optional-feature pattern of
     #: the git-sources env fallback).
     docs_repo: str = ""
+    #: Docs-push remote username (phase 173, ``BOR_DOCS_USER``) — paired
+    #: with ``docs_token``; travels to git as the ``GIT_CURL_USERNAME``
+    #: environment variable (``app/core/docs_push.py``, task 03) — never
+    #: in the command line. Empty (default) = no credentials: the push
+    #: is anonymous/URL-credential-free, exactly as before this phase.
+    docs_user: str = ""
+    #: Docs-push remote token (phase 173, ``BOR_DOCS_TOKEN``) — write-only
+    #: (catalogue ``secret=True``): the API reports ``has_value`` and never
+    #: the value (``value=None`` while masked); the admin panel renders
+    #: it masked. Travels to git as
+    #: ``GIT_CURL_PASSWORD`` (``app/core/docs_push.py``, task 03).
+    #: Empty (default) = the credential env is not set at all.
+    docs_token: str = ""
     #: The branch pushes land on (phase 59): each push cuts it fresh from
     #: ``docs_base_branch`` and ``git push --ff-only``s it — the owner
     #: opens the PR themselves (D3: no PR tooling). A git branch token,
diff --git a/app/core/docs_push.py b/app/core/docs_push.py
index 95b9604..8501283 100644
--- a/app/core/docs_push.py
+++ b/app/core/docs_push.py
@@ -22,6 +22,7 @@ stderr (the ``GitSyncError`` style), and the checkout under
 """
 from __future__ import annotations
 
+import os
 from pathlib import Path
 
 from scripts.git_sync import GitSyncError, run_git
@@ -61,9 +62,28 @@ def push_document(
     rel_path: str,
     content: str,
     commit_message: str,
+    user: str = "",
+    token: str = "",
 ) -> tuple[str, str]:
     """Commit *content* at *rel_path* and push (ff-only) to *branch*.
 
+    *user* / *token* are the docs-push credentials (phase 173, C2):
+    when *token* is non-blank, EVERY git step of the sequence runs with
+    git's documented HTTP credential environment —
+    ``GIT_CURL_USERNAME`` / ``GIT_CURL_PASSWORD`` (+
+    ``GIT_TERMINAL_PROMPT=0`` so a headless server fails fast instead
+    of hanging on a prompt) — merged over ``os.environ`` (the
+    subprocess env-replacement trap: a dict REPLACES the parent
+    environment, so the merge is what keeps ``PATH`` and friends).
+    The credential travels only in that environment — it never appears
+    in the argv (the clean *repo* URL stays in the argv untouched),
+    so it is absent from the process list. ``GIT_CURL_*`` is inert for
+    ``ssh://`` / local-path remotes (accepted — the remote decides).
+    **C5:** when *token* is blank (the default — an anonymous push to
+    a public or credential-free remote, exactly the pre-phase state),
+    every ``run_git`` call keeps ``env=None`` and the invocations are
+    byte-identical to the pre-phase ones.
+
     Step sequence (each step via :func:`scripts.git_sync.run_git`;
     ``cwd=work_dir`` once the checkout exists):
 
@@ -108,6 +128,19 @@ def push_document(
     """
     _refuse_unsafe_rel_path(rel_path)
     work = Path(work_dir).expanduser()
+    # C5: blank token → env stays None → every invocation below is
+    # byte-identical to the pre-phase one.
+    git_env: dict[str, str] | None = None
+    if token.strip():
+        # C2: git's documented HTTP credential env — never in the argv.
+        # GIT_TERMINAL_PROMPT=0 fails fast instead of hanging the headless
+        # server on a credential prompt.
+        git_env = {
+            **os.environ,
+            "GIT_CURL_USERNAME": user,
+            "GIT_CURL_PASSWORD": token,
+            "GIT_TERMINAL_PROMPT": "0",
+        }
     try:
         if not (work / ".git").exists():
             work.parent.mkdir(parents=True, exist_ok=True)
@@ -123,25 +156,30 @@ def push_document(
                     str(work),
                 ],
                 cwd=work.parent,
+                env=git_env,
             )
-        run_git(["git", "fetch", "--depth", "1", "origin", base_branch], cwd=work)
+        run_git(["git", "fetch", "--depth", "1", "origin", base_branch], cwd=work, env=git_env)
         # Capture the fetched base tip now — a *failed* fetch clears
         # FETCH_HEAD, so the symbolic ref cannot be reused later.
-        base_sha = run_git(["git", "rev-parse", "FETCH_HEAD"], cwd=work).strip()
+        base_sha = run_git(["git", "rev-parse", "FETCH_HEAD"], cwd=work, env=git_env).strip()
         try:
-            run_git(["git", "fetch", "--depth", "100", "origin", branch], cwd=work)
-            branch_sha = run_git(["git", "rev-parse", "FETCH_HEAD"], cwd=work).strip()
+            run_git(
+                ["git", "fetch", "--depth", "100", "origin", branch], cwd=work, env=git_env
+            )
+            branch_sha = run_git(
+                ["git", "rev-parse", "FETCH_HEAD"], cwd=work, env=git_env
+            ).strip()
         except GitSyncError:
             branch_sha = None  # the branch does not exist on the remote yet
-        if run_git(["git", "branch", "--list", branch], cwd=work).strip():
-            run_git(["git", "checkout", branch], cwd=work)
+        if run_git(["git", "branch", "--list", branch], cwd=work, env=git_env).strip():
+            run_git(["git", "checkout", branch], cwd=work, env=git_env)
         else:
             anchor = branch_sha if branch_sha is not None else base_sha
-            run_git(["git", "checkout", "-B", branch, anchor], cwd=work)
+            run_git(["git", "checkout", "-B", branch, anchor], cwd=work, env=git_env)
         target = work / rel_path
         target.parent.mkdir(parents=True, exist_ok=True)
         target.write_text(content, encoding="utf-8")
-        run_git(["git", "add", "--", rel_path], cwd=work)
+        run_git(["git", "add", "--", rel_path], cwd=work, env=git_env)
         run_git(
             [
                 "git",
@@ -156,9 +194,10 @@ def push_document(
                 commit_message,
             ],
             cwd=work,
+            env=git_env,
         )
-        run_git(["git", "push", "origin", branch], cwd=work)
-        sha = run_git(["git", "rev-parse", "HEAD"], cwd=work).strip()
+        run_git(["git", "push", "origin", branch], cwd=work, env=git_env)
+        sha = run_git(["git", "rev-parse", "HEAD"], cwd=work, env=git_env).strip()
     except GitSyncError as err:
         raise DocsPushError(str(err)) from err
     return branch, sha
diff --git a/app/core/settings_catalog.py b/app/core/settings_catalog.py
index b20852a..25a6abf 100644
--- a/app/core/settings_catalog.py
+++ b/app/core/settings_catalog.py
@@ -11,8 +11,9 @@ to do with each of the ``Settings`` fields:
   presentation metadata (``group`` + ``label``) and its capability
   flags:
 
-  - ``secret`` — write-only (LOCKED A4): the API reports ``is_set``,
-    never the plaintext; a saved value is masked on read.
+  - ``secret`` — write-only (LOCKED A4): the API reports ``has_value``
+    (and ``masked=True`` / ``value=None``), never the plaintext; a
+    saved value is masked on read.
   - ``restart_required`` — boot-wired (LOCKED A4): the middleware /
     engine / logging / static mount read it once at boot, so the
     override applies on the NEXT boot (the panel shows the badge).
@@ -301,6 +302,10 @@ CATALOG: dict[str, SettingMeta] = {
     "pdf_page_dir": SettingMeta("pdf_page_dir", "PDF", "PDF page dir"),
     # --- Docs push ---
     "docs_repo": SettingMeta("docs_repo", "Docs push", "Docs repo"),
+    "docs_user": SettingMeta("docs_user", "Docs push", "Docs user"),
+    "docs_token": SettingMeta(
+        "docs_token", "Docs push", "Docs token", secret=True
+    ),
     "docs_branch": SettingMeta("docs_branch", "Docs push", "Docs branch"),
     "docs_base_branch": SettingMeta(
         "docs_base_branch", "Docs push", "Docs base branch"
diff --git a/app/core/settings_migrate.py b/app/core/settings_migrate.py
new file mode 100644
index 0000000..bc7918a
--- /dev/null
+++ b/app/core/settings_migrate.py
@@ -0,0 +1,116 @@
+"""One-time settings migrations (phase 173).
+
+``migrate_legacy_docs_creds`` splits a legacy ``://user:pass@``
+``docs_repo`` value into ``docs_repo`` (clean) + ``docs_user`` +
+``docs_token`` — DB rows that SHADOW the env (the settings model's
+standing rule: the database wins over the environment). ``.env`` is
+never read for writing or rewritten. Idempotent: it runs only while
+no ``docs_token`` override exists, so owner-set values are never
+clobbered. One INFO line when it acts (AGENTS rule 10).
+
+The read side rides the overlay (``load_overrides`` /
+``resolve_settings`` — the same fail-soft engine); the write side is
+the PUT route's own write (an ``app_settings`` upsert through the app
+session — the overlay exposes no write path). A malformed
+``://user:pass@`` segment (an empty user OR pass) is NOT the legacy
+shape: the value stays as-is (the pre-phase behavior — nothing breaks,
+nothing half-migrates), no rows, no log.
+
+Called ONCE from ``create_app()`` (the composition root, task 04
+step 2), after the DB is available; a failure there logs a WARNING
+and never blocks startup — the app boots with the pre-phase behavior
+(the migration is a convenience, not a dependency).
+"""
+from __future__ import annotations
+
+import logging
+import re
+
+from sqlalchemy import func
+from sqlalchemy.dialects.postgresql import insert as pg_insert
+from sqlalchemy.orm import Session
+
+from app.core.settings_overlay import load_overrides, resolve_settings
+from app.db import SessionLocal
+from app.models import AppSetting
+
+logger = logging.getLogger("app.settings")
+
+#: ``://<user>:<pass>@`` — the legacy credentials-bearing docs-push
+#: remote (the phase-173 leak class). BOTH groups must be non-empty:
+#: ``://:@…`` / ``://u:@…`` are malformed, not the legacy shape. The
+#: same regex the PUT guard uses (``admin_settings._EMBEDDED_CREDS``)
+#: plus the capture groups; a ``://user:pass@`` subdomain cannot match
+#: (the character classes exclude ``/`` and the trailing ``@``
+#: requirement does the job).
+_EMBEDDED_CREDS = re.compile(r"://([^/@:]+):([^@/]+)@")
+
+
+def _write_rows(rows: dict[str, str]) -> None:
+    """Write one row per (key, value) into ``app_settings`` — the PUT
+    route's own write (INSERT … ON CONFLICT (key) DO UPDATE, the row's
+    ``updated_at`` moves), one session, one commit. The overlay
+    exposes no write path, so the direct upsert IS the write path.
+    ``.env`` is never touched (LOCKED A1 — the DB rows shadow the env;
+    the env file stays the base)."""
+    db: Session = SessionLocal()
+    try:
+        for key, value in rows.items():
+            stmt = pg_insert(AppSetting).values(key=key, value=value)
+            stmt = stmt.on_conflict_do_update(
+                index_elements=["key"],
+                set_={"value": stmt.excluded.value, "updated_at": func.now()},
+            )
+            db.execute(stmt)
+        db.commit()
+    finally:
+        db.close()
+
+
+def migrate_legacy_docs_creds() -> bool:
+    """The phase-173 C3 migration — split a legacy
+    ``://user:pass@`` ``docs_repo`` into three ``app_settings`` rows.
+
+    (1) read the ``app_settings`` overrides (the overlay's state);
+    (2) the target is the EFFECTIVE ``docs_repo`` (an override if
+    present, else the env value — what ``resolve_settings()``
+    resolves to); (3) match ``://<user>:<pass>@`` with BOTH groups
+    non-empty — otherwise no-op (a malformed segment stays as-is, the
+    pre-phase value: nothing breaks, nothing half-migrates); (4) a
+    ``docs_token`` override already present → no-op (idempotent —
+    owner-set values are never clobbered, and a previous run of this
+    migration counts as one); (5) otherwise write the three rows
+    (clean repo / user / token — the PUT route's own write) and log
+    ONE INFO line. Returns ``True`` when it acted, ``False`` for
+    every no-op shape. ``.env`` is never read for writing or
+    rewritten: the DB rows shadow the env (the settings model's
+    standing rule).
+    """
+    effective = resolve_settings().docs_repo
+    match = _EMBEDDED_CREDS.search(effective)
+    if match is None:
+        # (3) clean value OR malformed ``user:pass@`` (empty user or
+        # pass) — the pre-phase value stays as-is; no rows, no log.
+        return False
+    if "docs_token" in load_overrides():
+        # (4) idempotent: a token override (owner-set, or this
+        # migration's own previous run) is never clobbered.
+        return False
+    user, token = match.group(1), match.group(2)
+    # (5) the ``user:pass@`` segment removed, the ``://`` separator
+    # KEPT — ``https://u:pass@host/r.git`` → ``https://host/r.git``.
+    clean = effective.replace(match.group(0), "://", 1)
+    _write_rows(
+        {
+            "docs_repo": clean,
+            "docs_user": user,
+            "docs_token": token,
+        }
+    )
+    # ONE INFO line when it acts (AGENTS rule 10 — the value is never
+    # in the line, A4's log discipline).
+    logger.info(
+        "settings: migrated embedded docs-push credentials out of "
+        "docs_repo into docs_user/docs_token"
+    )
+    return True
diff --git a/app/main.py b/app/main.py
index 99f1198..7b16a91 100644
--- a/app/main.py
+++ b/app/main.py
@@ -52,6 +52,7 @@ from app.core.debugging import configure_debugging
 from app.core.logging import configure_logging
 from app.core.response_budget import ResponseBudgetMiddleware
 from app.core.security_headers import SecurityHeadersMiddleware
+from app.core.settings_migrate import migrate_legacy_docs_creds
 from app.core.settings_overlay import enabled as settings_db_enabled
 from app.core.settings_overlay import load_overrides, register_invalidator
 
@@ -118,6 +119,19 @@ def create_app() -> FastAPI:
         get_settings()
         logger.info("settings overrides loaded source=env-only disabled")
 
+    # Phase 173 (task 04, C3): the one-time startup migration — a
+    # legacy credentials-bearing ``docs_repo`` (env or DB) is split
+    # into ``app_settings`` rows (clean repo + ``docs_user`` +
+    # ``docs_token``); the DB rows shadow the env, ``.env`` is never
+    # rewritten, a second run is a no-op. Called ONCE, after the DB is
+    # available; a migration hiccup logs a WARNING and never blocks
+    # startup — the app boots with the pre-phase behavior (the
+    # migration is a convenience, not a dependency).
+    try:
+        migrate_legacy_docs_creds()
+    except Exception as exc:  # noqa: BLE001 — boot must never block
+        logger.warning("settings migration failed (%s)", type(exc).__name__)
+
     # Phase 168 (task 03): the settings panel's Save must retune the
     # running process, and app/core must never import app/api (PLAN §3's
     # direction) — so create_app(), the composition root, wires the
diff --git a/app/schemas.py b/app/schemas.py
index 9be00fe..b0dabf1 100644
--- a/app/schemas.py
+++ b/app/schemas.py
@@ -1997,7 +1997,7 @@ class AdminSettingItem(BaseModel):
     (``GET``/``PUT``/``DELETE /api/admin/settings[/{key}]``, phase 168,
     task 04).
 
-    One entry per ``Settings`` field (75 today — the catalogue is
+    One entry per ``Settings`` field (78 today — the catalogue is
     completeness-pinned, ``tests/unit/test_settings_catalog.py``), in
     ``GROUPS`` order: the field's metadata (``group`` + ``label`` + the
     three capability flags), where its EFFECTIVE value comes from
diff --git a/scripts/git_sync.py b/scripts/git_sync.py
index a62b2dc..30c43f6 100644
--- a/scripts/git_sync.py
+++ b/scripts/git_sync.py
@@ -317,7 +317,11 @@ def file_commit_dates(dest: Path | str) -> dict[str, datetime]:
         return {}
 
 
-def run_git(argv: list[str], cwd: Path) -> str:
+def run_git(
+    argv: list[str],
+    cwd: Path,
+    env: dict[str, str] | None = None,
+) -> str:
     """Run one git command, capturing output; raise GitSyncError on failure.
 
     The single ``git`` invocation point for the whole app (A11). Every
@@ -326,9 +330,16 @@ def run_git(argv: list[str], cwd: Path) -> str:
     handling stays uniform: captured stdout on success, and
     :class:`GitSyncError` carrying git's stderr on a non-zero exit (or
     when the git binary is missing from PATH).
+
+    ``env`` is passed through verbatim to :func:`subprocess.run`:
+    ``None`` (the default — the sync path's only form) inherits the
+    parent environment. **The subprocess env-replacement trap:** a dict
+    REPLACES the parent environment, so a caller that needs add-on
+    variables (the docs-push credential env, C2) must build a complete
+    environment (a merge over ``os.environ``) itself.
     """
     try:
-        proc = subprocess.run(argv, cwd=cwd, capture_output=True, text=True)
+        proc = subprocess.run(argv, cwd=cwd, capture_output=True, text=True, env=env)
     except FileNotFoundError:
         raise GitSyncError("git was not found on PATH — install git and retry") from None
     if proc.returncode != 0:
diff --git a/tests/e2e/test_admin_settings_panel.py b/tests/e2e/test_admin_settings_panel.py
index 412c67e..fc50340 100644
--- a/tests/e2e/test_admin_settings_panel.py
+++ b/tests/e2e/test_admin_settings_panel.py
@@ -553,7 +553,7 @@ def test_admin_sees_groups_and_source_badges(page: Page, app_url: str, db_ready:
             return el.scrollHeight > el.clientHeight;
         }"""
     )
-    assert scrolls, "75 rows must overflow the bounded card (the scroll must bite)"
+    assert scrolls, "78 rows must overflow the bounded card (the scroll must bite)"
 
     # The groups render in the server's order (the pinned display
     # groups — at least these two).
@@ -981,7 +981,12 @@ def test_clear_all_overrides(page: Page, app_url: str, db_ready: None) -> None:
     expect(page.locator("#settings-status")).to_contain_text(
         "Cleared 3 overrides.", timeout=30_000
     )
-    assert page.locator(".settings-src.is-db").count() == 0
+    # The re-GET settles the badges (the status line lands BEFORE the
+    # re-render — the §7.4 lifecycle); wait for the settled state
+    # rather than snapshotting a mid-flight render (the combined-run
+    # race — the 78-item catalog's re-GET can outlast the status
+    # poll's gap under a three-suite run, phase-173 regression pass).
+    expect(page.locator(".settings-src.is-db")).to_have_count(0, timeout=30_000)
     expect(page.locator('tr[data-key="app_name"] .settings-src')).to_have_text("env")
     expect(page.locator('tr[data-key="input_placeholder"] .settings-src')).to_have_text("env")
     expect(page.locator('tr[data-key="top_n_docs"] .settings-src')).to_have_text("default")
diff --git a/tests/e2e/test_docs_push_creds.py b/tests/e2e/test_docs_push_creds.py
new file mode 100644
index 0000000..e4b88b3
--- /dev/null
+++ b/tests/e2e/test_docs_push_creds.py
@@ -0,0 +1,531 @@
+"""Phase 173 E2E (Playwright): the docs-push credentials — the LEAK CLASS
+is dead in the real UI.
+
+Source: owner audit of the production admin Settings panel (2026-10-10)
+— ``BOR_DOCS_REPO`` was a plain-text row whose production value was a
+git URL with an embedded username + Gitea token: a live credential leak
+on the settings page, the raw HTML, and the settings API. This phase
+splits the credentials into ``docs_user`` (plain) + ``docs_token``
+(write-only, ``secret=True`` — the ``llm_api_key``-style row), guards
+the ``docs_repo`` PUT against embedded credentials (422), and migrates
+a legacy value once at startup (C1–C5, phase-locked).
+
+Run in isolation (DB must be up: ``podman compose up -d db``; the
+suite needs NO LLM — the mock is the house default, A16):
+
+    uv run pytest tests/e2e/test_docs_push_creds.py -v --no-cov
+
+Test → contract mapping (one phase, one isolated file — AGENTS rule 4):
+
+1. ``test_rows_render_token_write_only`` — the split shape in the
+   real UI: the ``Docs push`` group shows a ``Docs repo`` TEXT row
+   (the clean URL, seeded through the admin API), a ``Docs user``
+   TEXT row, and a ``Docs token`` row that is WRITE-ONLY — its
+   input is ``type=password``, NOT pre-filled (value ``""``),
+   rendered in the phase-168 secret-row style (the ``••••••
+   (stored)`` placeholder, the ``BOR_DOCS_TOKEN`` aria-label), with
+   the is-set state visible (DB badge + a live Reset) — and the
+   seeded token text is ABSENT from the initial page DOM, the
+   served HTML, and the raw ``GET /api/admin/settings`` body.
+2. ``test_save_stays_masked`` — the core assertion: typing a unique
+   sentinel token into the ``Docs token`` row and saving re-renders
+   the row masked; a reload of ``/settings.html`` keeps it masked
+   with the is-set state visible (DB badge, live Reset, API
+   ``has_value``), and the **sentinel is absent from the entire
+   page DOM** — ``page.content()`` must not contain it (nor must
+   the served HTML or the raw API body).
+3. ``test_reset_unsets`` — the row's Reset hands control back to the
+   environment: the status line, the Reset back to DISABLED (the
+   "no saved override" title — the phase-168 not-set marker for a
+   secret row; the placeholder is the constant ``•••••• (stored)``
+   for every secret row, set or not), the badge back to ``env``
+   (the env base is set-but-empty in the module app), the input
+   empty, the sentinel gone from the DOM, and the API reporting
+   ``has_value=false`` / ``has_override=false``.
+4. ``test_creds_url_guard_surfaces_and_stays_clean`` — the C4 guard
+   UI-side: with a clean ``docs_repo`` saved, typing a
+   credentials-bearing URL (``https://u:pass@e2e.invalid/o/r.git``)
+   and saving 422s — the ``role="alert"`` line names the field and
+   the replacement (the ``Docs user`` / ``Docs token`` fields) —
+   the input echoes the typed value (K4, the pre-save state, fine),
+   and after the failed save + reload the row keeps the PREVIOUS
+   saved value with the typed URL's ``pass`` segment ABSENT from
+   the page DOM and the API still reporting the clean URL.
+
+DB isolation: the shared e2e Postgres keeps ``app_settings`` (the
+overlay rows — a leftover row would retune every later suite's app
+through the conftest pin's failure mode) and ``ui_settings`` (the
+single row the caching middleware reads for EVERY served page)
+across suites. An autouse fixture truncates ``app_settings`` and
+``ui_settings`` and deletes the ``e2e-``-labeled tokens before AND
+after every test (never a TRUNCATE on ``api_tokens`` — the shared
+DB may hold the owner's real tokens); the module teardown pins
+``app_settings`` empty. The module app opts BACK IN over the
+conftest's global ``BOR_SETTINGS_DB=0`` pin (``env["BOR_SETTINGS_DB"]
+= "1"`` — the ``test_pictorial_pdf.py`` opt-in pattern) and pins the
+docs-push base vars to DISTINCTIVE empties (``BOR_DOCS_REPO`` /
+``BOR_DOCS_USER`` / ``BOR_DOCS_TOKEN`` = ``""``) so an operator's
+local (gitignored) ``.env`` — loaded by pydantic from
+``cwd=REPO`` — cannot leak a credentials-bearing repo (the startup
+migration's subject) or a real token into the suite's app: process
+env ranks above the ``.env`` file. A module-scope ``.env`` mtime
+guard pins LOCKED A1: no code path the suite drives opens the env
+file for writing.
+"""
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import uuid
+from collections.abc import Iterator
+from pathlib import Path
+from typing import Any
+
+import httpx
+import pytest
+from playwright.sync_api import Page, expect
+from sqlalchemy import text
+
+from app.config import Settings
+from app.db import SessionLocal
+from e2e.auth_helpers import login
+from e2e.conftest import (
+    ADMIN_PASSWORD,
+    SESSION_SECRET,
+    USE_REAL_LLM,
+    _wait_http,
+)
+
+REPO = Path(__file__).resolve().parents[2]
+
+#: The module app's OWN port (the test_response_to_docs.py pattern —
+#: the conftest session app owns 8123 in a combined run; a same-port
+#: second uvicorn dies on bind and would drive the wrong server).
+#: Env-overridable.
+APP_PORT = int(os.environ.get("E2E_APP_PORT_CREDS", "8190"))
+APP_URL = f"http://127.0.0.1:{APP_PORT}"
+
+#: The test-seed values (test 1) — distinctive so "the DB row now
+#: wins" is visible, and the seeded token is the value that must
+#: appear NOWHERE outside the DB.
+SEED_REPO = "https://gitea.example.com/e2e/docs.git"
+SEED_USER = "e2e-docs-push-user"
+SEED_TOKEN = "sk-e2e-docs-seed-0123456789abcd"
+
+#: Test 4 — the clean value the row KEEPS, and the credentials-bearing
+#: URL the guard must refuse (the ``pass`` segment must never persist).
+CLEAN_REPO = "https://gitea.example.com/e2e/docs.git"
+CRED_URL = "https://u:pass@e2e.invalid/o/r.git"
+
+#: The phase-168 secret-row placeholder (the frontend's constant for
+#: every ``secret=True`` row — settings.js's makeControl).
+STORED_PLACEHOLDER = "•••••• (stored)"
+
+
+# ---------------------------------------------------------------------------
+# Per-module app env (the phase-168 tuning/theme pattern)
+# ---------------------------------------------------------------------------
+
+
+def _boot_app() -> subprocess.Popen[bytes]:
+    """The module app (the shared env block + the phase-173 pins):
+    the overlay ON (``BOR_SETTINGS_DB=1`` — the module opts back in
+    over the conftest's global pin) and the docs-push base vars
+    pinned to DISTINCTIVE empties (an operator's local ``.env`` must
+    not leak a credentials-bearing repo or a real token in)."""
+    env = dict(os.environ)
+    env.pop("DEBUGPY", None)
+    env["BOR_ENVIRONMENT"] = "e2e"
+    env["BOR_STATIC_DIR"] = str(REPO / "frontend")
+    env["BOR_LLM_BASE_URL"] = (
+        "https://aipi.reeseapps.com/v1"
+        if USE_REAL_LLM
+        else f"http://127.0.0.1:{_MOCK_PORT}/v1"
+    )
+    # The E2E-calibrated gate pins (the conftest pattern — explicit so
+    # an operator's local .env cannot leak a different gate into the
+    # suite's app; the startup validator needs floor ≤ threshold).
+    env["BOR_RELEVANCE_THRESHOLD"] = "0.30"
+    env["BOR_LEXICAL_SUPPORT_FLOOR"] = "0.15"
+    env["BOR_SOURCE_USEFULNESS_FLOOR"] = "0.15"
+    env["BOR_LLM_RETRY_DELAY"] = "0"
+    env["BOR_LLM_RETRIES"] = str(Settings.model_fields["llm_retries"].default)
+    env.setdefault(
+        "BOR_DATABASE_URL",
+        "postgresql+psycopg://reese:reese@localhost:5432/brain_of_reese",
+    )
+    # Phase 16: admin auth must be set or create_app() refuses to boot.
+    env["BOR_ADMIN_PASSWORD"] = ADMIN_PASSWORD
+    env["BOR_SESSION_SECRET"] = SESSION_SECRET
+    # Phase 173 (this suite): the docs-push base pinned to empties —
+    # no credentials-bearing repo for the startup migration to act on,
+    # no real token in effect, and the "env" source badge deterministic
+    # (the var is set-but-empty → source "env", not "default").
+    env["BOR_DOCS_REPO"] = ""
+    env["BOR_DOCS_USER"] = ""
+    env["BOR_DOCS_TOKEN"] = ""
+    env["BOR_SUGGESTIONS"] = json.dumps(
+        Settings.model_fields["suggestions"].default
+    )
+    # Phase 168: the module opts BACK IN over the conftest's global
+    # BOR_SETTINGS_DB=0 pin (the test_pictorial_pdf.py pattern).
+    env["BOR_SETTINGS_DB"] = "1"
+    env["BOR_GIT_SOURCES"] = ""
+    return subprocess.Popen(
+        [sys.executable, "-m", "uvicorn", "app.main:app",
+         "--host", "127.0.0.1", "--port", str(APP_PORT), "--log-level", "warning"],
+        cwd=REPO,
+        env=env,
+    )
+
+
+def _stop_app(proc: subprocess.Popen[bytes]) -> None:
+    proc.terminate()
+    try:
+        proc.wait(timeout=10)
+    except subprocess.TimeoutExpired:
+        proc.kill()
+
+
+@pytest.fixture(scope="module")
+def app_server(mock_llm: int) -> Iterator[str]:
+    """The real app under test — the overlay ON (``BOR_SETTINGS_DB=1``)
+    and the docs-push base pinned to empties (the phase-173 pins)."""
+    global _MOCK_PORT
+    _MOCK_PORT = mock_llm
+    proc = _boot_app()
+    try:
+        _wait_http(f"{APP_URL}/api/health")
+        yield APP_URL
+    finally:
+        _stop_app(proc)
+
+
+@pytest.fixture(scope="module")
+def app_url(app_server: str) -> str:
+    return app_server
+
+
+# ---------------------------------------------------------------------------
+# DB isolation + helpers
+# ---------------------------------------------------------------------------
+
+
+def _clean_settings_state() -> None:
+    """Fresh settings + theme state per test: truncate ``app_settings``
+    (a leftover row is the cross-suite poison this phase's overlay
+    guard exists to prevent) and the single-row ``ui_settings``
+    (the middleware reads it for EVERY page), and delete this suite's
+    issued tokens (label-scoped on ``e2e-`` — never a TRUNCATE: the
+    shared DB may hold the owner's real tokens)."""
+    with SessionLocal() as db:
+        db.execute(text("TRUNCATE app_settings"))
+        db.execute(text("TRUNCATE ui_settings"))
+        db.execute(text("DELETE FROM api_tokens WHERE label LIKE 'e2e-%'"))
+        db.commit()
+
+
+@pytest.fixture(autouse=True)
+def _clean(db_ready: None) -> Iterator[None]:
+    _clean_settings_state()
+    yield
+    _clean_settings_state()
+    # The module's final state: app_settings EMPTY (the poison guard —
+    # the next suite's app must boot with no overrides).
+    with SessionLocal() as db:
+        assert db.execute(text("SELECT count(*) FROM app_settings")).scalar() == 0
+
+
+@pytest.fixture(scope="module", autouse=True)
+def _env_never_written() -> Iterator[None]:
+    """LOCKED A1, mtime-pinned: no code path the suite drives opens
+    ``.env`` for writing (the file is gitignored — a ``git status``
+    check cannot see it, so ``stat``'s mtime is the assertion)."""
+    env_file = REPO / ".env"
+    before = env_file.stat().st_mtime_ns if env_file.exists() else None
+    yield
+    after = env_file.stat().st_mtime_ns if env_file.exists() else None
+    assert before == after, "the app under test must never write .env"
+
+
+def _admin_client(app_url: str) -> httpx.Client:
+    """The API side of the form login (the 204 + the signed session
+    cookie in the jar)."""
+    client = httpx.Client(timeout=60.0)
+    r = client.post(f"{app_url}/api/login", json={"password": ADMIN_PASSWORD})
+    assert r.status_code == 204, f"admin login → {r.status_code}: {r.text[:120]}"
+    return client
+
+
+def _put_setting(
+    client: httpx.Client, app_url: str, key: str, value: str
+) -> httpx.Response:
+    r = client.put(f"{app_url}/api/admin/settings/{key}", json={"value": value})
+    assert r.status_code == 200, f"PUT {key} → {r.status_code}: {r.text[:200]}"
+    return r
+
+
+def _catalog_item(client: httpx.Client, app_url: str, key: str) -> dict[str, Any]:
+    r = client.get(f"{app_url}/api/admin/settings", timeout=30.0)
+    assert r.status_code == 200, r.text[:200]
+    for item in r.json()["items"]:
+        if item["key"] == key:
+            return item
+    raise AssertionError(f"{key} missing from the catalogue")
+
+
+def _unique_sentinel() -> str:
+    """The task's unique sentinel (a per-run uuid4 — "a saved token
+    never appears anywhere in the page DOM" is asserted against a
+    value that is unguessable, not a fixed constant)."""
+    return f"e2e-sentinel-{uuid.uuid4().hex}"
+
+
+# ---------------------------------------------------------------------------
+# 1. The rows render: the clean-URL text row, the user text row, and
+#    the WRITE-ONLY token row — masked, not pre-filled, absent from
+#    the initial DOM
+# ---------------------------------------------------------------------------
+
+
+def test_rows_render_token_write_only(page: Page, app_url: str, db_ready: None) -> None:
+    page.set_default_timeout(30_000)
+    # Seed all three rows THROUGH THE ADMIN API (before the initial
+    # page read — the panel's first GET must already see the stored
+    # values): the clean repo URL, the plain user, and the token
+    # (whose PUT response is the write-only contract — masked,
+    # value null).
+    client = _admin_client(app_url)
+    _put_setting(client, app_url, "docs_repo", SEED_REPO)
+    _put_setting(client, app_url, "docs_user", SEED_USER)
+    r = _put_setting(client, app_url, "docs_token", SEED_TOKEN)
+    assert r.json()["masked"] is True and r.json()["value"] is None
+
+    # The API's read side for the new key (the C1 pin — the phase-168
+    # secret contract, zero extra code): group / label / secret /
+    # value=null / has_value, and the plain user's value.
+    tok = _catalog_item(client, app_url, "docs_token")
+    assert tok["group"] == "Docs push" and tok["label"] == "Docs token"
+    assert tok["secret"] is True and tok["value"] is None
+    assert tok["has_value"] is True and tok["has_override"] is True
+    user = _catalog_item(client, app_url, "docs_user")
+    assert user["secret"] is False and user["value"] == SEED_USER
+    repo = _catalog_item(client, app_url, "docs_repo")
+    assert repo["value"] == SEED_REPO
+
+    # The UI: sign in → the ``Docs push`` group renders with the
+    # three rows in the catalogue's order…
+    login(page, app_url, next="/settings.html")
+    expect(page.locator("#settings-content")).to_be_visible(timeout=15_000)
+    expect(
+        page.locator("tr.settings-group-row", has_text="Docs push")
+    ).to_be_visible()
+    # …the ``Docs repo`` TEXT row (the clean URL, DB badge)…
+    repo_row = page.locator('tr[data-key="docs_repo"]')
+    expect(repo_row.locator(".cell-clip")).to_have_text("Docs repo")
+    repo_input = repo_row.locator(".settings-control")
+    assert repo_input.get_attribute("type") == "text"
+    expect(repo_input).to_have_value(SEED_REPO)
+    expect(repo_row.locator(".settings-src")).to_have_text("DB")
+    # …the ``Docs user`` TEXT row (the test-seed value, DB badge)…
+    user_row = page.locator('tr[data-key="docs_user"]')
+    expect(user_row.locator(".cell-clip")).to_have_text("Docs user")
+    user_input = user_row.locator(".settings-control")
+    assert user_input.get_attribute("type") == "text"
+    expect(user_input).to_have_value(SEED_USER)
+    expect(user_row.locator(".settings-src")).to_have_text("DB")
+    # …and the ``Docs token`` row that is WRITE-ONLY: type=password,
+    # NOT pre-filled (the stored value never reaches the input),
+    # rendered in the phase-168 secret-row style (the "(stored)"
+    # placeholder, the aria-label naming the env var), with the
+    # is-set state visible (the DB badge + a live Reset).
+    tok_row = page.locator('tr[data-key="docs_token"]')
+    expect(tok_row.locator(".cell-clip")).to_have_text("Docs token")
+    tok_input = tok_row.locator(".settings-control")
+    assert tok_input.get_attribute("type") == "password"
+    assert tok_input.input_value() == ""
+    assert tok_input.get_attribute("placeholder") == STORED_PLACEHOLDER
+    assert tok_input.get_attribute("aria-label") == "BOR_DOCS_TOKEN"
+    expect(tok_row.locator(".settings-src")).to_have_text("DB")
+    expect(tok_row.locator(".settings-reset")).to_be_enabled()
+
+    # The seeded token text is ABSENT from the initial DOM, the
+    # served HTML, and the raw API body (the LEAK CLASS — asserted
+    # on the raw text, not the parsed model).
+    assert SEED_TOKEN not in page.content(), "the seeded token leaked into the page"
+    raw_html = client.get(app_url + "/settings.html", timeout=10).text
+    assert SEED_TOKEN not in raw_html, "the seeded token leaked into the served HTML"
+    raw_api = client.get(f"{app_url}/api/admin/settings", timeout=30.0)
+    assert SEED_TOKEN not in raw_api.text, "the seeded token leaked into the API body"
+
+
+# ---------------------------------------------------------------------------
+# 2. The core assertion: a saved token stays masked — save, reload,
+#    the sentinel is absent from the entire page DOM
+# ---------------------------------------------------------------------------
+
+
+def test_save_stays_masked(page: Page, app_url: str, db_ready: None) -> None:
+    page.set_default_timeout(30_000)
+    login(page, app_url, next="/settings.html")
+    expect(page.locator("#settings-content")).to_be_visible(timeout=15_000)
+    client = _admin_client(app_url)
+
+    # The row starts NOT set (the module's docs base is set-but-
+    # empty): an empty password input, the constant "(stored)"
+    # placeholder, and a DISABLED Reset (the "no saved override"
+    # title — the phase-168 not-set marker).
+    tok_row = page.locator('tr[data-key="docs_token"]')
+    tok_input = tok_row.locator(".settings-control")
+    assert tok_input.input_value() == ""
+    expect(tok_row.locator(".settings-reset")).to_be_disabled()
+    expect(tok_row.locator(".settings-src")).to_have_text("env")
+
+    # Type a unique sentinel into the ``Docs token`` row → Save…
+    sentinel = _unique_sentinel()
+    page.fill('tr[data-key="docs_token"] .settings-control', sentinel)
+    expect(page.locator("#settings-dirty")).to_have_text("1 unsaved changes")
+    page.click("#settings-save")
+    expect(page.locator("#settings-status")).to_contain_text(
+        "Saved 1 settings.", timeout=30_000
+    )
+    # …the row re-renders masked: the input is EMPTY again (the
+    # typed value was sent, never painted back), the placeholder
+    # stands, and the is-set state is visible (DB badge + a live
+    # Reset).
+    assert tok_input.input_value() == ""
+    assert tok_input.get_attribute("placeholder") == STORED_PLACEHOLDER
+    expect(tok_row.locator(".settings-src")).to_have_text("DB")
+    expect(tok_row.locator(".settings-reset")).to_be_enabled()
+    assert sentinel not in page.content(), "the sentinel leaked into the page"
+
+    # Reload /settings.html (the panel re-reads the settled server
+    # state): the row is STILL masked…
+    page.goto(app_url + "/settings.html")
+    expect(page.locator("#settings-content")).to_be_visible(timeout=15_000)
+    tok_input = page.locator('tr[data-key="docs_token"] .settings-control')
+    assert tok_input.input_value() == ""
+    assert tok_input.get_attribute("placeholder") == STORED_PLACEHOLDER
+    # …with the is-set state visible (the DB badge + the live
+    # Reset)…
+    tok_row = page.locator('tr[data-key="docs_token"]')
+    expect(tok_row.locator(".settings-src")).to_have_text("DB")
+    expect(tok_row.locator(".settings-reset")).to_be_enabled()
+    # …and the API agrees (has_value, value null, no override
+    # plaintext).
+    tok = _catalog_item(client, app_url, "docs_token")
+    assert tok["has_value"] is True and tok["value"] is None
+
+    # THE core assertion: the sentinel is ABSENT from the entire
+    # page DOM — and from the served HTML and the raw API body.
+    assert sentinel not in page.content(), "the sentinel leaked into the reloaded page"
+    raw_html = client.get(app_url + "/settings.html", timeout=10).text
+    assert sentinel not in raw_html, "the sentinel leaked into the served HTML"
+    raw_api = client.get(f"{app_url}/api/admin/settings", timeout=30.0)
+    assert sentinel not in raw_api.text, "the sentinel leaked into the API body"
+
+
+# ---------------------------------------------------------------------------
+# 3. The Reset unsets: the row returns to the not-set state
+# ---------------------------------------------------------------------------
+
+
+def test_reset_unsets(page: Page, app_url: str, db_ready: None) -> None:
+    page.set_default_timeout(30_000)
+    login(page, app_url, next="/settings.html")
+    expect(page.locator("#settings-content")).to_be_visible(timeout=15_000)
+    client = _admin_client(app_url)
+
+    # Set the token from the panel (the same dirty-row flow)…
+    sentinel = _unique_sentinel()
+    page.fill('tr[data-key="docs_token"] .settings-control', sentinel)
+    page.click("#settings-save")
+    expect(page.locator("#settings-status")).to_contain_text(
+        "Saved 1 settings.", timeout=30_000
+    )
+    # …then the row's Reset: the status line…
+    page.click('tr[data-key="docs_token"] .settings-reset')
+    expect(page.locator("#settings-status")).to_contain_text(
+        "BOR_DOCS_TOKEN is back to the environment value.", timeout=30_000
+    )
+    # …and the row returns to the NOT-SET state: the Reset is
+    # DISABLED with the "no saved override" title (the phase-168
+    # not-set marker for a secret row — the "(stored)" placeholder
+    # is the frontend's constant for every secret row, set or not,
+    # so the badge + the Reset ARE the state), the badge is back
+    # to env (the module's set-but-empty base), the input is empty,
+    # and the sentinel is gone from the DOM.
+    tok_row = page.locator('tr[data-key="docs_token"]')
+    reset = tok_row.locator(".settings-reset")
+    expect(reset).to_be_disabled()
+    assert "no saved override" in (reset.get_attribute("title") or "")
+    expect(tok_row.locator(".settings-src")).to_have_text("env")
+    assert tok_row.locator(".settings-control").input_value() == ""
+    assert sentinel not in page.content(), "the sentinel survived the reset"
+    # The API agrees: the row is gone (has_override false, the
+    # set-but-empty env base → has_value false, value null).
+    tok = _catalog_item(client, app_url, "docs_token")
+    assert tok["has_override"] is False and tok["has_value"] is False
+    assert tok["value"] is None and tok["source"] == "env"
+
+
+# ---------------------------------------------------------------------------
+# 4. The C4 guard, UI-side: a credentials-bearing URL 422s, the row
+#    keeps the previous value, and the typed URL never persists
+# ---------------------------------------------------------------------------
+
+
+def test_creds_url_guard_surfaces_and_stays_clean(
+    page: Page, app_url: str, db_ready: None
+) -> None:
+    page.set_default_timeout(30_000)
+    login(page, app_url, next="/settings.html")
+    expect(page.locator("#settings-content")).to_be_visible(timeout=15_000)
+    client = _admin_client(app_url)
+
+    # Save a CLEAN docs_repo through the panel (the "previous
+    # value")…
+    page.fill('tr[data-key="docs_repo"] .settings-control', CLEAN_REPO)
+    page.click("#settings-save")
+    expect(page.locator("#settings-status")).to_contain_text(
+        "Saved 1 settings.", timeout=30_000
+    )
+    # …then type a CREDENTIALS-BEARING URL into the same row and
+    # save: the batch's single PUT hits the phase-173 guard (C4)…
+    page.fill('tr[data-key="docs_repo"] .settings-control', CRED_URL)
+    expect(page.locator("#settings-dirty")).to_have_text("1 unsaved changes")
+    page.click("#settings-save")
+    # …and the 422 surfaces (the phase-168 error-display contract —
+    # the role=alert line names the field AND the replacement).
+    error = page.locator("#settings-error")
+    expect(error).to_have_attribute("role", "alert")
+    expect(error).to_be_visible(timeout=30_000)
+    expect(error).to_contain_text("docs_repo")
+    expect(error).to_contain_text("Docs user / Docs token")
+    # K4: the input echoes the typed value (the pre-save state —
+    # that is fine; the assertion is on the saved/persisted state
+    # after the failed save + reload).
+    expect(
+        page.locator('tr[data-key="docs_repo"] .settings-control')
+    ).to_have_value(CRED_URL)
+    # The failed save stored NOTHING: the API still reports the
+    # clean URL as the value (db — the previously saved row).
+    repo = _catalog_item(client, app_url, "docs_repo")
+    assert repo["value"] == CLEAN_REPO and repo["source"] == "db"
+
+    # Reload: the row KEEPS the previous (clean) value, and the
+    # typed URL — its ``pass`` segment above all — is ABSENT from
+    # the page DOM and the raw API body (never shown as a saved
+    # value).
+    page.goto(app_url + "/settings.html")
+    expect(page.locator("#settings-content")).to_be_visible(timeout=15_000)
+    expect(
+        page.locator('tr[data-key="docs_repo"] .settings-control')
+    ).to_have_value(CLEAN_REPO)
+    assert CRED_URL not in page.content(), "the credentials-bearing URL persisted"
+    assert "u:pass@" not in page.content(), "the URL's pass segment persisted"
+    raw_api = client.get(f"{app_url}/api/admin/settings", timeout=30.0)
+    assert CRED_URL not in raw_api.text
+    assert "u:pass@" not in raw_api.text
diff --git a/tests/integration/test_admin_settings_api.py b/tests/integration/test_admin_settings_api.py
index a7c7094..935f809 100644
--- a/tests/integration/test_admin_settings_api.py
+++ b/tests/integration/test_admin_settings_api.py
@@ -9,7 +9,7 @@ The pins (00_phase, Testing & Quality):
 * the auth matrix — anonymous AND a signed-in token USER get 403 on ALL
   four routes (the router-wide ``require_admin`` closes the surface on
   every method), the admin 200s on all four;
-* the shape — ``items`` length == ``len(Settings.model_fields)`` (75),
+* the shape — ``items`` length == ``len(Settings.model_fields)`` (78),
   groups in ``GROUPS`` order (the stable order the E2E pins against),
   ``totals.count`` / ``overridden`` correct, ``overlay_enabled`` true;
   on an empty table a field whose ``BOR_*`` var the test env sets
@@ -152,7 +152,7 @@ def test_auth_matrix_all_four_routes(client: TestClient, db: Session) -> None:
 
 
 def test_catalogue_shape_and_sources_on_empty_table(admin_client) -> None:
-    """The whole catalogue, grouped and stable: 75 items (exactly
+    """The whole catalogue, grouped and stable: 78 items (exactly
     ``Settings.model_fields``), groups in ``GROUPS`` order (each group a
     contiguous block, the block order = ``GROUPS``), ``totals`` correct,
     ``overlay_enabled`` true. On an empty table: the env-var-set field
@@ -418,7 +418,7 @@ def test_kill_switch_disables_the_mechanism_not_the_panel(
 def test_catalogue_stays_under_the_byte_budget(admin_client) -> None:
     """The whole catalogue stays under the phase-167 INFO bar (64 KB —
     ``BOR_LOG_LARGE_RESPONSE_BYTES``), so ``GET /api/admin/settings``
-    never floods the log (75 items ≈ 20 KB; the audit script re-verifies
+    never floods the log (78 items ≈ 20 KB; the audit script re-verifies
     the 256 KB budget in task 06)."""
     r = admin_client.get(API)
     assert r.status_code == 200
@@ -602,3 +602,166 @@ def test_llm_thinking_level_row_contract(
     anon = TestClient(fastapi_app)
     r = anon.put(f"{API}/llm_thinking_level", json={"value": "high"})
     assert r.status_code == 403 and r.json() == {"detail": "admin only"}
+
+
+def test_docs_token_is_write_only_masked_end_to_end(
+    admin_client: TestClient, db: Session, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """Phase 173 (task 02, C1): ``docs_token`` is a write-only
+    ``secret=True`` row — the EXISTING generic secret contract pinned
+    for the new key (no new code): (a) before a save the GET reports
+    the row in the ``Docs push`` group, ``secret=true``,
+    ``value=null`` (masked) and ``has_value=false`` — with
+    ``docs_user`` a plain ``str`` row at ``""``; (b) a PUT stores it
+    (200) and the GET reports ``has_value=true`` with the plaintext
+    NOWHERE in the raw body — the core pin: the token text is absent
+    from the response JSON, the leak class this phase kills; (c) a
+    blank PUT 422s (the self-lockout guard — ``DELETE`` is the
+    explicit clear) and the stored value is unchanged; (d) a DELETE
+    unsets it (reset to the env value — ``""`` by default).
+    """
+    # A deterministic base (machine-independent, the phase-172 test's
+    # idiom): an explicit empty process value for both docs
+    # credentials — the process env RANKS ABOVE the operator's local
+    # ``.env`` (the conftest pin's reasoning), so this pins the code
+    # defaults no matter what the machine's ``.env`` carries.
+    monkeypatch.setenv("BOR_DOCS_USER", "")
+    monkeypatch.setenv("BOR_DOCS_TOKEN", "")
+    invalidate_settings()
+
+    # (a) the rows: docs_token masked + unset, docs_user plain + empty.
+    r = admin_client.get(API)
+    assert r.status_code == 200, r.text
+    item = _item(r.json(), "docs_token")
+    assert item["group"] == "Docs push"
+    assert item["label"] == "Docs token"
+    assert item["type"] == "str"
+    assert item["env_var"] == "BOR_DOCS_TOKEN"
+    assert item["secret"] is True
+    assert item["restart_required"] is False
+    assert item["overridable"] is True
+    assert item["masked"] is True
+    assert item["value"] is None
+    assert item["db_value"] is None
+    assert item["has_value"] is False
+    assert item["has_override"] is False
+    assert item["default"] == ""  # masked: the code default is never shown
+    user = _item(r.json(), "docs_user")
+    assert user["group"] == "Docs push"
+    assert user["label"] == "Docs user"
+    assert user["secret"] is False
+    assert user["masked"] is False
+    assert user["value"] == ""
+    assert user["has_value"] is False
+
+    # (b) a PUT stores it (200, the RAW string in app_settings) and the
+    # GET reports has_value=true with the plaintext NOWHERE in the raw
+    # body (asserted on response.text, not the parsed model).
+    r = admin_client.put(f"{API}/docs_token", json={"value": "bor-docs-tok-123"})
+    assert r.status_code == 200, r.text
+    assert r.json()["masked"] is True
+    assert r.json()["value"] is None
+    assert r.json()["has_value"] is True
+    assert r.json()["source"] == "db"
+    assert db.execute(
+        text("SELECT value FROM app_settings WHERE key = 'docs_token'")
+    ).scalar() == "bor-docs-tok-123"  # stored, exactly as sent
+    assert get_settings().docs_token == "bor-docs-tok-123"  # live, no restart
+
+    r = admin_client.get(API)
+    assert r.status_code == 200
+    item = _item(r.json(), "docs_token")
+    assert item["has_value"] is True
+    assert item["value"] is None
+    assert item["db_value"] is None
+    assert "bor-docs-tok-123" not in r.text  # NOWHERE in the raw body
+
+    # (c) a blank PUT is a 422 (a blank token would self-lockout —
+    # DELETE is the explicit clear) and the stored value is unchanged.
+    r = admin_client.put(f"{API}/docs_token", json={"value": "   "})
+    assert r.status_code == 422
+    assert "BOR_DOCS_TOKEN must not be blank" in r.json()["detail"]
+    assert db.execute(
+        text("SELECT value FROM app_settings WHERE key = 'docs_token'")
+    ).scalar() == "bor-docs-tok-123"  # unchanged
+
+    # (d) a DELETE unsets it: the row is gone and the effective value is
+    # back to the env value (the pinned "" — the anonymous state, C5).
+    r = admin_client.delete(f"{API}/docs_token")
+    assert r.status_code == 200, r.text
+    assert r.json()["source"] == "env"  # the pinned empty BOR_DOCS_TOKEN
+    assert r.json()["has_override"] is False
+    assert r.json()["has_value"] is False
+    assert get_settings().docs_token == ""  # the override is gone
+    assert db.execute(
+        text("SELECT count(*) FROM app_settings WHERE key = 'docs_token'")
+    ).scalar() == 0  # the row is gone
+
+
+def test_docs_repo_refuses_embedded_credentials(
+    admin_client: TestClient, db: Session, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """Phase 173 (task 02, C4): a ``docs_repo`` PUT with a
+    ``://<user>:<pass>@`` segment is a 422 that NAMES the Docs user /
+    Docs token fields (asserted in the detail, not just present) and
+    stores NOTHING — the leak cannot be re-created from the UI. Clean
+    ``https://`` URLs, local paths and ``ssh://`` remotes pass
+    untouched; a ``user:``-looking subdomain (no trailing ``@``) does
+    NOT false-positive. A legacy ``.env`` value with embedded
+    credentials is NOT a PUT — the task-04 startup migration handles
+    that path."""
+    # A deterministic base: explicit empty/valid process values for the
+    # docs settings — the process env ranks above the operator's local
+    # ``.env`` (the conftest pin's reasoning), so the base is the code
+    # defaults no matter what the machine's ``.env`` carries (a local
+    # ``BOR_DOCS_REPO`` with embedded credentials is EXACTLY the leak
+    # class under test — it must not leak into this pin).
+    monkeypatch.setenv("BOR_DOCS_REPO", "")
+    monkeypatch.setenv("BOR_DOCS_BRANCH", "bor-docs")
+    invalidate_settings()
+
+    # The 422: names the replacement fields, stores nothing.
+    r = admin_client.put(
+        f"{API}/docs_repo", json={"value": "https://u:pass@gitea.example.com/o/r.git"}
+    )
+    assert r.status_code == 422
+    detail = r.json()["detail"]
+    assert "Docs user" in detail
+    assert "Docs token" in detail
+    assert db.execute(text("SELECT count(*) FROM app_settings")).scalar() == 0
+    # The failed write did not disturb the live view.
+    assert get_settings().docs_repo == ""
+
+    # Clean https:// URL: passes (the branch validator is satisfied by
+    # the non-empty docs_branch default — the repo is set, the token
+    # shape is valid).
+    r = admin_client.put(f"{API}/docs_repo", json={"value": "https://gitea.example.com/o/r.git"})
+    assert r.status_code == 200, r.text
+    assert r.json()["db_value"] == "https://gitea.example.com/o/r.git"
+    assert get_settings().docs_repo == "https://gitea.example.com/o/r.git"
+    assert admin_client.delete(f"{API}/docs_repo").status_code == 200
+
+    # A local path: untouched.
+    r = admin_client.put(f"{API}/docs_repo", json={"value": "/srv/docs-repo"})
+    assert r.status_code == 200, r.text
+    assert r.json()["db_value"] == "/srv/docs-repo"
+    assert admin_client.delete(f"{API}/docs_repo").status_code == 200
+
+    # A ``user:``-looking subdomain: the trailing ``@`` requirement keeps
+    # the regex from false-positiving — passes untouched.
+    r = admin_client.put(
+        f"{API}/docs_repo", json={"value": "https://sub.domain.example.com/r.git"}
+    )
+    assert r.status_code == 200, r.text
+    assert r.json()["db_value"] == "https://sub.domain.example.com/r.git"
+    assert admin_client.delete(f"{API}/docs_repo").status_code == 200
+
+    # An ssh:// remote (credentials via SSH keys, never in the URL):
+    # untouched.
+    r = admin_client.put(
+        f"{API}/docs_repo", json={"value": "ssh://git@gitea.example.com/o/r.git"}
+    )
+    assert r.status_code == 200, r.text
+    assert r.json()["db_value"] == "ssh://git@gitea.example.com/o/r.git"
+    assert admin_client.delete(f"{API}/docs_repo").status_code == 200
+    assert db.execute(text("SELECT count(*) FROM app_settings")).scalar() == 0
diff --git a/tests/integration/test_docs_push_migrate.py b/tests/integration/test_docs_push_migrate.py
new file mode 100644
index 0000000..6830ea5
--- /dev/null
+++ b/tests/integration/test_docs_push_migrate.py
@@ -0,0 +1,203 @@
+"""Integration: the phase-173 (task 04, C3) legacy-credentials
+migration, end-to-end against the real ``app_settings`` table.
+
+The shape (the 00_phase / task-04 pins):
+
+* seed env ``BOR_DOCS_REPO=https://u:pass@host/r.git`` (no DB rows)
+  → run the migration (the direct call — the ``create_app()`` wiring
+  is covered by the unit seam in ``test_main.py``) → the migration
+  returns ``True`` and the three rows land in ``app_settings``
+  (clean repo / ``docs_user`` / ``docs_token``);
+* DB rows SHADOW the env — the effective settings resolve the clean
+  URL + the credentials FROM the DB (the env value still embeds the
+  credentials, ``.env`` is never rewritten: the process env is
+  untouched by the migration);
+* idempotent — a second run is a no-op (``False``, the rows
+  byte-identical);
+* the settings API reports the clean ``docs_repo`` (``source="db"``)
+  and the ``docs_token`` masked (``secret=true``, ``value=null``,
+  ``has_value=true``) with the token text NOWHERE in the raw body —
+  the leak is gone from the page.
+
+The module's teardown leaves NO row behind (the ``test_admin_settings_
+api`` discipline — a surviving row would retune every later suite
+through the overlay).
+
+Real Postgres (``podman compose up -d db``); no LLM involved.
+
+Requires:  podman compose up -d db
+"""
+from __future__ import annotations
+
+import os
+from collections.abc import Iterator
+
+import pytest
+from fastapi.testclient import TestClient
+from sqlalchemy import text
+from sqlalchemy.orm import Session
+
+from app.api import chat as chat_api
+from app.config import get_settings, invalidate_settings
+from app.core import settings_overlay
+from app.core.settings_migrate import migrate_legacy_docs_creds
+from app.core.settings_overlay import register_invalidator, resolve_settings
+from app.main import app as fastapi_app
+from tests.conftest import ADMIN_PASSWORD
+
+API = "/api/admin/settings"
+
+#: The legacy value the migration splits (the production shape — the
+#: token is distinctive so the "absent from the raw body" pin cannot
+#: false-positive on a catalogue label).
+_LEGACY = "https://u:tok-legacy-123@host/r.git"
+
+
+@pytest.fixture(autouse=True)
+def clean_state(
+    db: Session, monkeypatch: pytest.MonkeyPatch
+) -> Iterator[None]:
+    """A clean ``app_settings`` table + the overlay switch ON + a
+    fresh overlay/hook slate (the ``test_admin_settings_api`` idiom:
+    reset the process-wide hook list and re-wire what
+    ``create_app()`` wires). Teardown deletes the rows + invalidates
+    + clears the cache — NO row may survive this module (a surviving
+    row would retune every later suite through the overlay)."""
+    settings_overlay.reset_state_for_tests()
+    register_invalidator(chat_api.reset_runtime_caches)
+    db.execute(text("DELETE FROM app_settings"))
+    db.commit()
+    monkeypatch.setenv("BOR_SETTINGS_DB", "1")
+    monkeypatch.setenv("BOR_DOCS_REPO", "")
+    invalidate_settings()
+    get_settings.cache_clear()
+    yield
+    db.execute(text("DELETE FROM app_settings"))
+    db.commit()
+    invalidate_settings()
+    get_settings.cache_clear()
+    settings_overlay.reset_state_for_tests()
+
+
+def _table(db: Session) -> dict[str, str]:
+    """The whole ``app_settings`` table (the display fact, never a
+    query surface — one SELECT)."""
+    return {
+        key: value
+        for key, value in db.execute(
+            text("SELECT key, value FROM app_settings")
+        )
+    }
+
+
+def _admin_client() -> TestClient:
+    """A fresh client signed in as the admin (the ``_admin_client``
+    pattern from ``test_ui_settings_api``)."""
+    client = TestClient(fastapi_app)
+    r = client.post("/api/login", json={"password": ADMIN_PASSWORD})
+    assert r.status_code == 204, f"admin login failed: {r.status_code}"
+    return client
+
+
+def _item(body: dict, key: str) -> dict:
+    """One catalogue item by key (the GET body's ``items`` list)."""
+    for item in body["items"]:
+        if item["key"] == key:
+            return item
+    raise AssertionError(f"catalogue item missing: {key}")
+
+
+def test_legacy_env_is_split_into_db_rows(
+    db: Session, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """The end-to-end shape: seed env (no DB rows) → migration runs →
+    the three rows land, the effective settings resolve the clean URL
+    + the credentials FROM THE DB (the rows shadow the env), the env
+    is untouched (``.env`` is never rewritten), and the second run is
+    a no-op (idempotent)."""
+    monkeypatch.setenv("BOR_DOCS_REPO", _LEGACY)
+    assert _table(db) == {}  # no DB rows (the fixture's clean slate)
+
+    assert migrate_legacy_docs_creds() is True
+
+    # the three rows — the clean repo + user + token, and NOTHING
+    # else (the leak class dies: the repo row no longer carries the
+    # credentials).
+    rows = _table(db)
+    assert rows == {
+        "docs_repo": "https://host/r.git",
+        "docs_user": "u",
+        "docs_token": "tok-legacy-123",
+    }
+
+    # the effective settings resolve FROM THE DB (invalidate first —
+    # the module import primed the cache before this module's rows):
+    # the clean URL shadows the credentials-bearing env value.
+    invalidate_settings()
+    effective = resolve_settings()
+    assert effective.docs_repo == "https://host/r.git"
+    assert effective.docs_user == "u"
+    assert effective.docs_token == "tok-legacy-123"
+
+    # the env is untouched — the migration never rewrites the env
+    # (``.env`` stays the base; the DB rows shadow it).
+    assert os.environ["BOR_DOCS_REPO"] == _LEGACY
+
+    # idempotent: the ``docs_token`` row is present now — a second
+    # run is a no-op, the rows byte-identical.
+    assert migrate_legacy_docs_creds() is False
+    assert _table(db) == rows
+
+
+def test_migrated_values_are_masked_on_the_settings_api(
+    db: Session, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """Completion criterion (the leak is gone from the page): after a
+    (b)-shape migration the settings API reports the clean
+    ``docs_repo`` (``source="db"``) + ``docs_token``
+    ``secret=true`` / ``value=null`` / ``has_value=true`` (masked)
+    with the token text NOWHERE in the raw response body."""
+    monkeypatch.setenv("BOR_DOCS_REPO", _LEGACY)
+    assert migrate_legacy_docs_creds() is True
+    invalidate_settings()
+
+    admin = _admin_client()
+    r = admin.get(API)
+    assert r.status_code == 200, r.text
+
+    repo = _item(r.json(), "docs_repo")
+    assert repo["value"] == "https://host/r.git"  # the clean URL
+    assert repo["source"] == "db"  # the DB row is in effect
+    assert repo["db_value"] == "https://host/r.git"
+
+    token = _item(r.json(), "docs_token")
+    assert token["secret"] is True
+    assert token["masked"] is True
+    assert token["value"] is None  # write-only: never the value
+    assert token["db_value"] is None  # a masked row never exposes text
+    assert token["has_value"] is True  # a value IS in effect
+    assert token["has_override"] is True  # the DB row
+    assert token["source"] == "db"
+
+    user = _item(r.json(), "docs_user")
+    assert user["value"] == "u"
+    assert user["source"] == "db"
+
+    # the core pin: the token text is NOWHERE in the raw body (the
+    # leak class this phase kills — asserted on response.text, not
+    # the parsed model; the value is distinctive so the substring
+    # check cannot false-positive on a catalogue label).
+    assert "tok-legacy-123" not in r.text
+
+
+def test_migration_is_a_noop_for_a_clean_env(
+    db: Session, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """The no-op shape end-to-end: a clean env URL (the pre-phase
+    state) → ``False``, the table stays empty (nothing half-
+    migrates, nothing written)."""
+    monkeypatch.setenv("BOR_DOCS_REPO", "https://host/r.git")
+    assert migrate_legacy_docs_creds() is False
+    assert _table(db) == {}
+    invalidate_settings()
+    assert resolve_settings().docs_repo == "https://host/r.git"
diff --git a/tests/unit/test_admin_settings_api.py b/tests/unit/test_admin_settings_api.py
index cb6f162..0152d2b 100644
--- a/tests/unit/test_admin_settings_api.py
+++ b/tests/unit/test_admin_settings_api.py
@@ -6,8 +6,8 @@ opens a file (``.env`` is never written), never shells out and never
 ``eval``s a value.
 
 The DB-driven behavior (the four routes, the candidate-set validation,
-the auth matrix) is pinned in
-``tests/integration/test_admin_settings_api.py``.
+the auth matrix, the phase-173 ``docs_repo`` guard on the PUT path)
+is pinned in ``tests/integration/test_admin_settings_api.py``.
 """
 from __future__ import annotations
 
@@ -15,8 +15,14 @@ import pathlib
 import re
 
 import pytest
+from fastapi import HTTPException
 
-from app.api.admin_settings import _display, _field_type, _item
+from app.api.admin_settings import (
+    _display,
+    _field_type,
+    _item,
+    _refuse_embedded_credentials,
+)
 from app.config import Settings
 from app.core.settings_overlay import LIST_FIELDS
 
@@ -172,3 +178,46 @@ def test_module_never_writes_files_or_shells_out() -> None:
     assert "os.system" not in source
     assert re.search(r"\beval\s*\(", source) is None
     assert "import shutil" not in source and "shutil." not in source
+
+
+def test_refuse_embedded_credentials_fires_only_for_docs_repo() -> None:
+    """Phase 173 (task 02, C4): the guard 422s for ``docs_repo`` with a
+    ``://<user>:<pass>@`` segment — the detail NAMES the Docs user /
+    Docs token fields — and passes everything else: other keys (only
+    ``docs_repo`` is guarded), clean ``https://`` URLs, local paths,
+    ``ssh://`` remotes, and a ``user:``-looking subdomain (the
+    trailing ``@`` requirement keeps it from false-positiving).
+    An empty user OR an empty pass (``://:pass@`` / ``://u:@``) does
+    NOT match — the ``+`` quantifiers require both to be non-empty.
+    """
+    # The 422: names the replacement fields.
+    with pytest.raises(HTTPException) as excinfo:
+        _refuse_embedded_credentials(
+            "docs_repo", "https://u:pass@gitea.example.com/o/r.git"
+        )
+    assert excinfo.value.status_code == 422
+    assert "Docs user" in excinfo.value.detail
+    assert "Docs token" in excinfo.value.detail
+    # Also a ``git://``-style URL with embedded credentials (the regex
+    # is scheme-agnostic: it keys on ``://<user>:<pass>@``).
+    with pytest.raises(HTTPException):
+        _refuse_embedded_credentials("docs_repo", "git://u:tok@host.example.com/r.git")
+
+    # Other keys: never guarded (``docs_user`` may hold any plain text).
+    _refuse_embedded_credentials("docs_user", "https://u:pass@host.example.com/r.git")
+    _refuse_embedded_credentials("llm_api_key", "://u:pass@")
+
+    # Clean shapes pass: https URL, local path, ssh remote.
+    _refuse_embedded_credentials("docs_repo", "https://gitea.example.com/o/r.git")
+    _refuse_embedded_credentials("docs_repo", "/srv/docs-repo")
+    _refuse_embedded_credentials("docs_repo", "ssh://git@gitea.example.com/o/r.git")
+    # A subdomain that looks like ``user:`` (no trailing ``@``).
+    _refuse_embedded_credentials("docs_repo", "https://sub.domain.example.com/r.git")
+    # Empty user OR empty pass: the ``+`` quantifiers require both
+    # non-empty — no match (a bare ``://`` is not the leak class).
+    _refuse_embedded_credentials("docs_repo", "https://:pass@host.example.com/r.git")
+    _refuse_embedded_credentials("docs_repo", "https://u:@host.example.com/r.git")
+    # A ``:`` after the ``@`` segment (a URL with no credentials at
+    # all) and an empty value.
+    _refuse_embedded_credentials("docs_repo", "https://host.example.com/r.git:3000")
+    _refuse_embedded_credentials("docs_repo", "")
diff --git a/tests/unit/test_config.py b/tests/unit/test_config.py
index cd670b5..d0e66df 100644
--- a/tests/unit/test_config.py
+++ b/tests/unit/test_config.py
@@ -665,6 +665,42 @@ def test_docs_branch_env_override(monkeypatch: pytest.MonkeyPatch) -> None:
     assert s.docs_base_branch == "master"
 
 
+def test_docs_creds_defaults_are_empty(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Phase 173 (task 01, C5): no credentials by default — the push is
+    anonymous/URL-credential-free, exactly as before this phase."""
+    monkeypatch.delenv("BOR_DOCS_USER", raising=False)
+    monkeypatch.delenv("BOR_DOCS_TOKEN", raising=False)
+    s = _settings()
+    assert s.docs_user == ""
+    assert s.docs_token == ""
+
+
+def test_docs_creds_env_overrides(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Phase 173 (task 01): ``BOR_DOCS_USER`` / ``BOR_DOCS_TOKEN``
+    resolve verbatim — plain ``str``, no coercion."""
+    monkeypatch.setenv("BOR_DOCS_USER", "alice")
+    monkeypatch.setenv("BOR_DOCS_TOKEN", "tok")
+    s = _settings()
+    assert s.docs_user == "alice"
+    assert s.docs_token == "tok"
+
+
+def test_docs_creds_empty_env_stays_empty(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Phase 173 (task 01, C5): an empty (or whitespace) env value stays
+    ``""`` / verbatim — no coercion, no normalization away from empty.
+    The anonymous state must stay expressible: the settings must NOT
+    strip the token, or an explicit empty would become a set credential.
+    (Whitespace is stored verbatim, like ``docs_repo``; the *push*
+    service decides the empty-vs-set semantics, not the settings.)"""
+    monkeypatch.setenv("BOR_DOCS_USER", "")
+    monkeypatch.setenv("BOR_DOCS_TOKEN", "")
+    s = _settings()
+    assert s.docs_user == ""
+    assert s.docs_token == ""
+    monkeypatch.setenv("BOR_DOCS_TOKEN", "   ")
+    assert _settings().docs_token == "   "
+
+
 def test_docs_work_dir_env_override_is_raw_string(monkeypatch: pytest.MonkeyPatch) -> None:
     monkeypatch.setenv("BOR_DOCS_WORK_DIR", "/data/bor/docs")
     s = _settings()
diff --git a/tests/unit/test_docs_push.py b/tests/unit/test_docs_push.py
index 5ebde3d..ed248f3 100644
--- a/tests/unit/test_docs_push.py
+++ b/tests/unit/test_docs_push.py
@@ -9,19 +9,33 @@ ever involved.
 
 The module skips (``pytest.skip``) when ``git --version`` fails — a
 machine without git must not see hard failures.
+
+Phase 173 (C2/C5) adds a mocked-``run_git`` section: the FULL 10-step
+sequence is exercised against a fake git (no real repo) to pin the
+credential transport — no token → every step gets ``env=None``
+(byte-identical to the pre-phase call); a token → every step gets
+``GIT_CURL_USERNAME`` / ``GIT_CURL_PASSWORD`` / ``GIT_TERMINAL_PROMPT=0``
+merged over a controlled ``os.environ`` (``PATH`` survives the
+subprocess env-replacement trap); a whitespace-only token = empty;
+and a failing step still raises :class:`DocsPushError` with git's
+stderr, credential-agnostic.
 """
 from __future__ import annotations
 
 import subprocess
 from pathlib import Path
+from typing import TypedDict
 
 import pytest
 
+import app.core.docs_push as docs_push_mod
 from app.core.docs_push import DocsPushError, push_document
+from scripts.git_sync import GitSyncError
 
 BASE = "main"
 BRANCH = "bor-docs"
 REL = "docs/note.md"
+CLEAN_REPO = "https://git.example.com/docs.git"  # phase 173: the credential-free form
 IDENTITY = ("-c", "commit.gpgsign=false", "-c", "user.name=Test", "-c", "user.email=t@example.com")
 
 
@@ -198,3 +212,158 @@ def test_unsafe_rel_path_is_refused_before_any_git(bare_repo: Path, tmp_path: Pa
             )
     # No checkout was even attempted.
     assert not (tmp_path / "w").exists()
+
+
+# --- phase 173: credentials on the wire (C2/C5, mocked git) ---------------
+
+
+class _GitCall(TypedDict):
+    """One recorded ``run_git`` call (argv / cwd / env)."""
+
+    argv: list[str]
+    cwd: Path
+    env: dict[str, str] | None
+
+
+def _fake_run_git(
+    monkeypatch: pytest.MonkeyPatch, push_stderr: str = ""
+) -> list[_GitCall]:
+    """Monkeypatch ``app.core.docs_push.run_git``; record each call
+    (argv / cwd / env).
+
+    The FULL 10-step sequence runs: clone (the work dir is absent) →
+    the base fetch → the ``FETCH_HEAD`` capture → the branch fetch
+    (ALWAYS raises — the branch does not exist on the remote yet,
+    the swallowed path) → the branch probe → ``checkout -B`` → add →
+    commit → push (raises when *push_stderr* is set — the
+    un-swallowed failure, task 03 5d) → the ``HEAD`` capture. Returns
+    ``(BRANCH, "b" * 40)`` on success.
+    """
+    calls: list[_GitCall] = []
+
+    def fake_run(
+        argv: list[str], cwd: Path, env: dict[str, str] | None = None
+    ) -> str:
+        calls.append({"argv": list(argv), "cwd": cwd, "env": env})
+        key = tuple(argv)
+        if key == ("git", "fetch", "--depth", "100", "origin", BRANCH):
+            raise GitSyncError(
+                f"git fetch --depth 100 origin {BRANCH} failed (exit 128): "
+                f"fatal: couldn't find remote ref {BRANCH}"
+            )
+        if push_stderr and key == ("git", "push", "origin", BRANCH):
+            raise GitSyncError(
+                f"git push origin {BRANCH} failed (exit 128): {push_stderr}"
+            )
+        if key[:2] == ("git", "rev-parse"):
+            return "a" * 40 if key[-1] == "FETCH_HEAD" else "b" * 40
+        return ""
+
+    monkeypatch.setattr(docs_push_mod, "run_git", fake_run)
+    return calls
+
+
+def _args(work: Path) -> dict[str, str]:
+    return dict(
+        repo=CLEAN_REPO,
+        base_branch=BASE,
+        branch=BRANCH,
+        work_dir=str(work),
+        rel_path=REL,
+        content="# Note\n",
+        commit_message="docs: note",
+    )
+
+
+def test_no_token_env_is_none_on_every_step(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """Task 03 5a (C5 byte-identity pin): default args (no token) →
+    EVERY git step of the full sequence gets ``env=None`` — the
+    pre-phase ``subprocess.run`` shape, unchanged."""
+    work = tmp_path / "work"  # absent — the clone step runs too
+    calls = _fake_run_git(monkeypatch)
+
+    branch, sha = push_document(**_args(work))
+
+    assert (branch, sha) == (BRANCH, "b" * 40)
+    assert len(calls) == 10  # clone, fetch×2, rev-parse×2, branch, checkout, add, commit, push
+    for call in calls:
+        assert call["env"] is None
+    # The CLEAN URL stays in the argv (the credential never appears
+    # because it is not passed at all).
+    assert calls[0]["argv"][-2] == CLEAN_REPO
+
+
+def test_token_env_on_every_step_merged_over_environ(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """Task 03 5b (C2): token set → EVERY git step of a successful push
+    gets the 3-var credential env MERGED OVER a controlled
+    ``os.environ`` — ``PATH`` survives the subprocess
+    env-replacement trap, the credential never lands in the argv,
+    and the clean URL stays in it."""
+    monkeypatch.setenv("PATH", "/usr/bin")
+    monkeypatch.setenv("BOR_TEST_ENV", "sentinel")
+    work = tmp_path / "work"
+    calls = _fake_run_git(monkeypatch)
+
+    push_document(**_args(work), user="alice", token="s3cret")
+
+    assert len(calls) == 10
+    for call in calls:
+        env = call["env"]
+        assert isinstance(env, dict)
+        assert env["GIT_CURL_USERNAME"] == "alice"
+        assert env["GIT_CURL_PASSWORD"] == "s3cret"
+        assert env["GIT_TERMINAL_PROMPT"] == "0"
+        assert env["PATH"] == "/usr/bin"  # the merge-over-os.environ pin
+        assert env["BOR_TEST_ENV"] == "sentinel"  # the parent env survives
+        # C2: the credential travels ONLY in the environment.
+        assert "alice" not in call["argv"]
+        assert "s3cret" not in call["argv"]
+    # The clean URL is in the argv, untouched.
+    assert CLEAN_REPO in calls[0]["argv"]
+
+
+def test_whitespace_only_token_is_treated_as_empty(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """Task 03 5c (the ``.strip()`` rule): a whitespace-only token is
+    the no-credentials state → every step gets ``env=None``."""
+    calls = _fake_run_git(monkeypatch)
+
+    push_document(**_args(tmp_path / "work"), user="alice", token="   ")
+
+    assert len(calls) == 10
+    for call in calls:
+        assert call["env"] is None
+
+
+def test_failing_step_raises_docs_push_error_with_and_without_credentials(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """Task 03 5d: a failing step (the push) still raises
+    :class:`DocsPushError` with git's stderr — the error path is
+    credential-agnostic (with and without the credential env); the
+    failing step itself still carries the credential env when a token
+    is set."""
+    stderr = "fatal: rejected (simulated non-fast-forward)"
+
+    # without credentials (C5 — the pre-phase error path)
+    calls = _fake_run_git(monkeypatch, push_stderr=stderr)
+    with pytest.raises(DocsPushError) as excinfo:
+        push_document(**_args(tmp_path / "w1"))
+    msg = str(excinfo.value)
+    assert f"git push origin {BRANCH} failed (exit 128): {stderr}" in msg
+    assert calls[-1]["env"] is None  # the failed push step — no env
+
+    # with credentials (the error carries the full stderr for logs;
+    # the API layer's sanitize_error stays the defense-in-depth)
+    calls = _fake_run_git(monkeypatch, push_stderr=stderr)
+    with pytest.raises(DocsPushError) as excinfo:
+        push_document(**_args(tmp_path / "w2"), user="alice", token="s3cret")
+    msg = str(excinfo.value)
+    assert f"git push origin {BRANCH} failed (exit 128): {stderr}" in msg
+    assert isinstance(calls[-1]["env"], dict)
+    assert calls[-1]["env"]["GIT_CURL_PASSWORD"] == "s3cret"
diff --git a/tests/unit/test_git_sync.py b/tests/unit/test_git_sync.py
index dbd8c9e..66e2b33 100644
--- a/tests/unit/test_git_sync.py
+++ b/tests/unit/test_git_sync.py
@@ -297,6 +297,36 @@ def test_run_git_captures_and_returns_stdout(
     assert len(calls) == 1
 
 
+def test_run_git_default_env_is_none_and_reaches_subprocess(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """Phase 173 (C5 byte-identity pin): the default ``env=None`` is
+    passed through verbatim to ``subprocess.run`` — the pre-phase call
+    shape, so every sync-path invocation is unchanged."""
+    calls = _fake_run(monkeypatch, stdout="ok")
+
+    assert git_sync.run_git(["git", "version"], cwd=tmp_path) == "ok"
+    assert len(calls) == 1
+    assert "env" in calls[0]
+    assert calls[0]["env"] is None
+
+
+def test_run_git_explicit_env_reaches_subprocess_verbatim(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """Phase 173 (C2): an explicit env dict reaches ``subprocess.run``
+    verbatim — ``run_git`` neither merges over nor mutates the parent
+    environment (the env-replacement trap is the caller's contract;
+    the docs-push sequence does its own ``os.environ`` merge)."""
+    calls = _fake_run(monkeypatch, stdout="ok")
+    env = {"A": "b"}
+
+    assert git_sync.run_git(["git", "version"], cwd=tmp_path, env=env) == "ok"
+    assert len(calls) == 1
+    assert calls[0]["env"] is env  # the SAME object — passed through verbatim
+    assert calls[0]["env"] == {"A": "b"}
+
+
 # --- phase 135: the branch pin (the argv matrix) ----------------------------
 
 
diff --git a/tests/unit/test_main.py b/tests/unit/test_main.py
index b92de4f..c49d1a7 100644
--- a/tests/unit/test_main.py
+++ b/tests/unit/test_main.py
@@ -1,6 +1,8 @@
 """Unit tests: app factory edge cases (no live DB needed)."""
 from __future__ import annotations
 
+import logging
+
 from fastapi.testclient import TestClient
 
 import app.main as main_mod
@@ -51,3 +53,34 @@ def test_create_app_boots_with_the_switch_on(monkeypatch) -> None:
     # settings, and the hook slate is fresh for them too.
     settings_overlay.reset_state_for_tests()
     get_settings.cache_clear()
+
+
+def test_create_app_migration_failure_warns_and_boots(
+    monkeypatch, caplog
+) -> None:
+    """Phase 173 (task 04, C3): a migration failure logs a WARNING
+    and never blocks startup — the app still boots (with the
+    pre-phase behavior: the migration is a convenience, not a
+    dependency). The seam: the migration is monkeypatched to raise;
+    the real migration is a no-op in a DB-less unit environment
+    (the overlay's fail-soft read + the conftest-pinned empty
+    ``BOR_DOCS_REPO``), so the boot path is otherwise unchanged."""
+    settings_overlay.reset_state_for_tests()
+
+    def _boom() -> bool:
+        raise RuntimeError("migration hiccup")
+
+    monkeypatch.setattr(main_mod, "migrate_legacy_docs_creds", _boom)
+    with caplog.at_level(logging.WARNING, logger="app"):
+        app2 = main_mod.create_app()
+    assert app2 is not None
+    warnings = [
+        record.getMessage() for record in caplog.records
+        if record.levelno == logging.WARNING
+    ]
+    assert "settings migration failed (RuntimeError)" in warnings
+    # restore: the hook slate is fresh for the later suites, and the
+    # cache clear keeps a boot-time row set from leaking into their
+    # settings.
+    settings_overlay.reset_state_for_tests()
+    get_settings.cache_clear()
diff --git a/tests/unit/test_settings_catalog.py b/tests/unit/test_settings_catalog.py
index 083f3f0..020137a 100644
--- a/tests/unit/test_settings_catalog.py
+++ b/tests/unit/test_settings_catalog.py
@@ -54,12 +54,15 @@ def test_every_meta_carries_its_own_key() -> None:
 
 def test_secrets_are_exactly_the_masked_set() -> None:
     # LOCKED A4: write-only, masked — the 3 named secrets +
-    # database_url (read-only, but its URL carries credentials).
+    # database_url (read-only, but its URL carries credentials) +
+    # docs_token (phase 173, C1: the docs-push remote token reuses the
+    # write-only/masked mechanism, llm_api_key-style).
     assert set(SECRETS) == {
         "llm_api_key",
         "admin_password",
         "session_secret",
         "database_url",
+        "docs_token",
     }
 
 
@@ -108,6 +111,38 @@ def test_llm_thinking_level_is_a_plain_live_overridable_row() -> None:
     assert "llm_thinking_level" not in NON_OVERRIDABLE
 
 
+def test_docs_user_is_a_plain_live_overridable_row() -> None:
+    """Phase 173 (task 01, C1/C5): ``docs_user`` sits in ``Docs push``
+    with the ``Docs user`` label and is plain — not ``secret`` (a
+    plain username), not ``restart_required`` (the push service reads
+    the setting per push via ``get_settings()`` — live), overridable
+    (the overlay is generic over ``str`` fields). An empty value is a
+    valid state (C5: the anonymous push)."""
+    meta = CATALOG["docs_user"]
+    assert meta.group == "Docs push"
+    assert meta.label == "Docs user"
+    assert meta.secret is False
+    assert "docs_user" not in SECRETS
+    assert "docs_user" not in RESTART_REQUIRED
+    assert "docs_user" not in NON_OVERRIDABLE
+
+
+def test_docs_token_is_a_secret_live_overridable_row() -> None:
+    """Phase 173 (task 01, C1): ``docs_token`` has the ``Docs token``
+    label and ``secret=True`` — write-only end-to-end via the EXISTING
+    derived mechanism (``SECRETS`` picks it up automatically; the API
+    reports ``is_set`` + ``value=null``, a blank PUT 422s, the panel
+    renders it masked, zero ``settings.js`` code). Live (the push
+    service reads it per push), overridable (generic ``str`` overlay)."""
+    meta = CATALOG["docs_token"]
+    assert meta.group == "Docs push"
+    assert meta.label == "Docs token"
+    assert meta.secret is True
+    assert "docs_token" in SECRETS
+    assert "docs_token" not in RESTART_REQUIRED
+    assert "docs_token" not in NON_OVERRIDABLE
+
+
 def test_labels_nonempty_and_unique() -> None:
     labels = [meta.label for meta in CATALOG.values()]
     assert all(label.strip() for label in labels), "empty label in the catalogue"
diff --git a/tests/unit/test_settings_migrate.py b/tests/unit/test_settings_migrate.py
new file mode 100644
index 0000000..e689d7e
--- /dev/null
+++ b/tests/unit/test_settings_migrate.py
@@ -0,0 +1,270 @@
+"""Phase 173 (task 04, C3): the one-time startup migration of a
+legacy credentials-bearing ``docs_repo``.
+
+Pure/unit level — no live DB: the ``app_settings`` read is a stubbed
+overlay engine (the ``test_settings_overlay`` fake-engine idiom), the
+write path is monkeypatched (``settings_migrate._write_rows`` — it
+captures the rows AND mirrors them into the stubbed read store, so
+``resolve_settings()`` resolves the DB rows the migration wrote — the
+DB-shadowing pin), the env base comes from ``os.environ`` (``tests/
+conftest.py`` pins ``BOR_DOCS_REPO=`` / ``BOR_SETTINGS_DB=0`` — the
+fixture flips the switch on per test), and the overlay state is
+reset by ``reset_state_for_tests()``.
+"""
+from __future__ import annotations
+
+import logging
+from collections.abc import Iterator
+
+import pytest
+
+from app.core import settings_migrate, settings_overlay
+from app.core.settings_overlay import resolve_settings
+
+#: The ONE INFO line the migration logs when it acts (AGENTS rule 10).
+_MIGRATED_LINE = (
+    "settings: migrated embedded docs-push credentials out of "
+    "docs_repo into docs_user/docs_token"
+)
+
+
+class _FakeStore:
+    """A controllable ``app_settings`` store: the read (a fake overlay
+    engine) and the write (the monkeypatched ``_write_rows``) share
+    one dict — a migration write is visible to ``resolve_settings()``
+    on the next resolution (the DB-shadowing pin)."""
+
+    def __init__(self, rows: dict[str, str] | None = None) -> None:
+        self.rows = dict(rows or {})
+        self.writes: list[dict[str, str]] = []
+
+    def install(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        store = self
+
+        class _Rows:
+            def __iter__(self) -> object:
+                return iter(sorted(store.rows.items()))
+
+        class _FakeConn:
+            def execute(self, _stmt: object) -> _Rows:
+                return _Rows()
+
+            def __enter__(self) -> _FakeConn:
+                return self
+
+            def __exit__(self, *exc: object) -> bool:
+                return False
+
+        class _FakeEngine:
+            def connect(self) -> _FakeConn:  # type: ignore[no-untyped-def]
+                return _FakeConn()
+
+        monkeypatch.setattr(
+            settings_overlay, "_get_engine", lambda: _FakeEngine()
+        )
+
+        def _fake_write(rows: dict[str, str]) -> None:
+            store.writes.append(dict(rows))
+            store.rows.update(rows)
+
+        monkeypatch.setattr(settings_migrate, "_write_rows", _fake_write)
+
+
+@pytest.fixture(autouse=True)
+def _clean_state(monkeypatch: pytest.MonkeyPatch) -> Iterator[None]:
+    settings_overlay.reset_state_for_tests()
+    monkeypatch.setenv("BOR_SETTINGS_DB", "1")
+    monkeypatch.setenv("BOR_DOCS_REPO", "")
+    monkeypatch.setenv("BOR_DOCS_USER", "")
+    monkeypatch.setenv("BOR_DOCS_TOKEN", "")
+    yield
+    settings_overlay.reset_state_for_tests()
+
+
+def _migrated_lines(caplog: pytest.LogCaptureFixture) -> list[str]:
+    """The ``app.settings`` records that carry the migration line."""
+    return [
+        record.getMessage()
+        for record in caplog.records
+        if _MIGRATED_LINE in record.getMessage()
+    ]
+
+
+# ---------------------------------------------------------------------------
+# (a) the no-op shapes — clean value, malformed segment
+# ---------------------------------------------------------------------------
+
+
+def test_clean_env_url_is_a_noop(monkeypatch: pytest.MonkeyPatch) -> None:
+    """(a) a clean env URL with no overrides: ``False``, no rows
+    written (the pre-phase behavior stands untouched)."""
+    store = _FakeStore()
+    store.install(monkeypatch)
+    monkeypatch.setenv("BOR_DOCS_REPO", "https://host/r.git")
+    assert settings_migrate.migrate_legacy_docs_creds() is False
+    assert store.writes == []
+    assert store.rows == {}
+
+
+def test_clean_db_override_is_a_noop(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """(a, the DB-source variant) a clean URL arriving as a DB
+    override (the effective value, not the env): still a no-op."""
+    store = _FakeStore({"docs_repo": "https://host/r.git"})
+    store.install(monkeypatch)
+    monkeypatch.setenv("BOR_DOCS_REPO", "https://elsewhere/r.git")
+    assert settings_migrate.migrate_legacy_docs_creds() is False
+    assert store.writes == []
+    assert store.rows == {"docs_repo": "https://host/r.git"}
+
+
+def test_malformed_empty_user_is_a_noop(
+    monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture
+) -> None:
+    """(d) a malformed ``://:@…`` (empty user) is NOT the legacy
+    shape: ``False``, no rows, no log — the value stays as-is
+    (nothing breaks, nothing half-migrates)."""
+    store = _FakeStore()
+    store.install(monkeypatch)
+    monkeypatch.setenv("BOR_DOCS_REPO", "https://:@host/r.git")
+    with caplog.at_level(logging.INFO, logger="app.settings"):
+        assert settings_migrate.migrate_legacy_docs_creds() is False
+    assert store.writes == []
+    assert store.rows == {}
+    assert _migrated_lines(caplog) == []
+
+
+def test_malformed_empty_pass_is_a_noop(
+    monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture
+) -> None:
+    """(d, the other malformation) an empty pass (``://u:@…``):
+    the same no-op contract — no rows, no log."""
+    store = _FakeStore()
+    store.install(monkeypatch)
+    monkeypatch.setenv("BOR_DOCS_REPO", "https://u:@host/r.git")
+    with caplog.at_level(logging.INFO, logger="app.settings"):
+        assert settings_migrate.migrate_legacy_docs_creds() is False
+    assert store.writes == []
+    assert store.rows == {}
+    assert _migrated_lines(caplog) == []
+
+
+def test_subdomain_is_not_a_false_positive(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """A ``://user:pass@``-shaped SUBDOMAIN (no trailing ``@`` in
+    the URL) must not match — the character classes + the trailing
+    ``@`` requirement do that job (the same contract the PUT guard
+    pins)."""
+    store = _FakeStore()
+    store.install(monkeypatch)
+    monkeypatch.setenv("BOR_DOCS_REPO", "https://sub.domain.example.com/r.git")
+    assert settings_migrate.migrate_legacy_docs_creds() is False
+    assert store.writes == []
+
+
+# ---------------------------------------------------------------------------
+# (b) the migration shape — split, DB-shadowing, the one INFO line
+# ---------------------------------------------------------------------------
+
+
+def test_legacy_env_url_is_split_into_three_rows(
+    monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture
+) -> None:
+    """(b) a legacy env URL with no overrides: ``True``, exactly the
+    three rows (clean repo / user / token), and
+    ``resolve_settings()`` resolves the clean URL + the credentials
+    FROM THE DB rows (they shadow the env — the env value still
+    embeds the credentials, the effective value does not)."""
+    store = _FakeStore()
+    store.install(monkeypatch)
+    monkeypatch.setenv("BOR_DOCS_REPO", "https://u:pass@host/r.git")
+    with caplog.at_level(logging.INFO, logger="app.settings"):
+        assert settings_migrate.migrate_legacy_docs_creds() is True
+    assert store.rows == {
+        "docs_repo": "https://host/r.git",
+        "docs_user": "u",
+        "docs_token": "pass",
+    }
+    assert len(store.writes) == 1  # one write call, one row set
+    # DB rows SHADOW the env: the effective value is the clean URL.
+    effective = resolve_settings()
+    assert effective.docs_repo == "https://host/r.git"
+    assert effective.docs_user == "u"
+    assert effective.docs_token == "pass"
+    # (e) the INFO line is emitted exactly once — and it carries no
+    # value (the log discipline, A4).
+    assert _migrated_lines(caplog) == [_MIGRATED_LINE]
+    for line in _migrated_lines(caplog):
+        assert "pass" not in line
+
+
+def test_second_run_is_a_silent_noop(
+    monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture
+) -> None:
+    """(b + idempotency) after a migration wrote the three rows, the
+    second run finds the ``docs_token`` row → ``False``, no rows
+    written, NO second INFO line (the one-line pin, e)."""
+    store = _FakeStore()
+    store.install(monkeypatch)
+    monkeypatch.setenv("BOR_DOCS_REPO", "https://u:pass@host/r.git")
+    with caplog.at_level(logging.INFO, logger="app.settings"):
+        assert settings_migrate.migrate_legacy_docs_creds() is True
+        assert settings_migrate.migrate_legacy_docs_creds() is False
+    assert len(store.writes) == 1
+    assert _migrated_lines(caplog) == [_MIGRATED_LINE]
+
+
+def test_legacy_value_from_a_db_override_is_split(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """(b, the DB-source variant) the legacy value arriving as a DB
+    ``docs_repo`` override (the effective value): the same split —
+    the override row is rewritten clean, the credentials join the
+    new rows."""
+    store = _FakeStore({"docs_repo": "https://u:pass@host/r.git"})
+    store.install(monkeypatch)
+    monkeypatch.setenv("BOR_DOCS_REPO", "")  # env empty — DB is the source
+    assert settings_migrate.migrate_legacy_docs_creds() is True
+    assert store.rows == {
+        "docs_repo": "https://host/r.git",
+        "docs_user": "u",
+        "docs_token": "pass",
+    }
+    effective = resolve_settings()
+    assert effective.docs_repo == "https://host/r.git"
+
+
+# ---------------------------------------------------------------------------
+# (c) the clobber guard — an existing docs_token override stands
+# ---------------------------------------------------------------------------
+
+
+def test_existing_token_override_is_never_clobbered(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """(c) a legacy env URL while a ``docs_token`` override already
+    exists (owner-set, or a previous migration): ``False`` — the
+    pre-existing rows are untouched (no clobber)."""
+    store = _FakeStore({"docs_token": "owner-token"})
+    store.install(monkeypatch)
+    monkeypatch.setenv("BOR_DOCS_REPO", "https://u:pass@host/r.git")
+    assert settings_migrate.migrate_legacy_docs_creds() is False
+    assert store.writes == []
+    assert store.rows == {"docs_token": "owner-token"}  # byte-identical
+    # the effective value resolves the owner's token, not the URL's.
+    assert resolve_settings().docs_token == "owner-token"
+
+
+def test_existing_token_override_with_clean_repo_is_a_noop(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """(c, the clean variant) a token override with a clean repo
+    (env or DB): ``False`` — nothing to do, nothing touched."""
+    store = _FakeStore({"docs_token": "owner-token"})
+    store.install(monkeypatch)
+    monkeypatch.setenv("BOR_DOCS_REPO", "https://host/r.git")
+    assert settings_migrate.migrate_legacy_docs_creds() is False
+    assert store.writes == []
+    assert store.rows == {"docs_token": "owner-token"}