pushframe 5.0.3__tar.gz → 5.0.5__tar.gz

{pushframe-5.0.3 → pushframe-5.0.5}/.planning/MILESTONES.md

@@ -1,5 +1,30 @@
 # Milestones
 
+## v5.0 — Distribution & Rename: pushframe packages (Shipped: 2026-09-29)
+
+**Phases completed:** 3 phases (20-22), 4 plans — the first milestone
+about *shipping the tool itself* rather than its features.
+
+**Key accomplishments:**
+
+| Phase | Delivered | Proof |
+|-------|-----------|-------|
+| 20 — Rename & repo switch | `auraframes`→`pushframe` (module, binary, config migration), env `PUSHFRAME_*` primary, standalone repo `coredmp95/pushframe` (not a fork), MIT LICENSE + provenance | 407 tests green through the rename; live migration validated; name cleared on PyPI + trademark-adjacency checked |
+| 21 — Debian + APT | Hermetic `.deb` (embedded CPython 3.14, lintian 0E/0W, clean removal), signed APT repo live on GitHub Pages, container journeys for both channels | bytecode-ownership defect caught by our own container test and fixed for every user; live-URL journey exit 0 |
+| 22 — PyPI + releases | Trusted publishing (OIDC, zero PyPI tokens), tag-triggered release workflow, `--version` single-sourced, OPERATOR-STEPS + CHANGELOG | v5.0.2 run all-green 5/5 jobs; v5.0.3 carries the Changelog URL |
+
+**Shipped releases:** 5.0.0 → 5.0.1 (page metadata) → 5.0.2 (first
+pipeline-complete) → 5.0.3 (changelog URL) — each on PyPI + TestPyPI +
+APT + GitHub Releases simultaneously. First real deployment:
+venus.coredmp.net via the signed APT repo (human-driven: keyring →
+sources → install).
+
+**Known gaps carried forward:** 5.0.0 remains on PyPI (empty page,
+immutable) — yank candidate; `AURA_*` env vars in a one-release
+deprecation window; credentials still live in env vars/.env (v5.1's
+charter: config wizard + token-first sessions).
+
+
 ## v4.0 Local Google Photos Album Sync (Shipped: 2026-09-29)
 
 **Phases completed:** 4 phases (16-19), 10 plans, offline suite 349 → **401 tests**

{pushframe-5.0.3 → pushframe-5.0.5}/.planning/PROJECT.md

@@ -364,3 +364,5 @@ sequences write-path reliability first, then Google account linking → album di
 album-to-frame mirroring via a pruned local cache, then the carried debt. Biggest open
 unknown: whether Google's post-March-2025 Photos API still permits enumerating a user's own
 albums, or whether album selection has to go through the Picker API.*
+
+**Current Milestone:** v5.1 — Operations: Config, Sessions, Multi-frame & Scheduling (started 2026-09-29)

pushframe-5.0.5/.planning/REQUIREMENTS.md

@@ -0,0 +1,118 @@
+# Requirements: pushframe — v5.1 Operations: Config, Sessions, Multi-frame & Scheduling
+
+**Defined:** 2026-09-29
+**Core Value:** `pushframe` becomes *operable unattended*: configuration is a
+conversation (`pushframe config`) instead of env-var archaeology, the Aura
+password never touches disk (token-first sessions), mirrors run on a schedule
+without root (systemd user timers), one album can mirror to every frame
+(named mappings), and every command that needs a machine prerequisite fails
+with the remedy instead of a traceback.
+
+## Requirements
+
+### Config wizard (CFG)
+
+- [ ] **CFG-01**: `pushframe config` (interactive) asks for and stores: Aura
+  email, Aura secret, default frame name, and the tool's non-secret settings
+  (default album, write-budget override, debug) — prompts are masked for
+  secrets (getpass-style), values are validated (email shape; login test on
+  request), and the result is written to `~/.config/pushframe/config.json`
+  with mode `0600`. Re-running edits in place (existing values shown
+  redacted, Enter keeps).
+- [ ] **CFG-02**: precedence is `env var > config file > built-in default`
+  everywhere the CLI reads configuration; the env vars keep working exactly
+  as today (deprecation window opened in 5.0.0 stays honored); `pushframe
+  config show` prints the *effective* configuration with secrets redacted
+  and the source of each value (env/file/default).
+- [ ] **CFG-03**: `pushframe config import` migrates an existing `.env`
+  (or exported `PUSHFRAME_*`/`AURA_*` set) into `config.json` without
+  retyping; the command reports what it took from where and never stores
+  what it could resolve from the environment instead.
+- [ ] **CFG-04**: `pushframe config path` prints the config file location;
+  `pushframe config set <key> <value>` / `get <key>` exist for scripts;
+  unknown keys fail with the list of known keys.
+
+### Credential handling (SEC — token-first)
+
+- [ ] **SEC-01**: the Aura password is **never persisted** — not in
+  `config.json`, not in env files the tool writes. `pushframe config`
+  authenticates once, stores the returned `auth_token` (0600) plus the
+  account email, and discards the password when the process exits.
+- [ ] **SEC-02**: every command that needs the API uses the stored token
+  (header auth) and falls back to interactive password login **only** when
+  the token is absent/expired/revoked, after which the new token is
+  persisted; a `--password` / `PUSHFRAME_PASSWORD` override still wins
+  (CI/script path) but is documented as discouraged for humans.
+- [ ] **SEC-03**: `pushframe logout` deletes the stored token (and only the
+  token); token material never appears in logs, output, or the history
+  ledger (existing redaction stays enforced by tests).
+
+### Scheduling (TMR — systemd user)
+
+- [ ] **TMR-01**: `pushframe schedule add <job>` installs a systemd **user**
+  timer + service unit under `~/.config/systemd/user/` for the supported
+  jobs (`google-sync --apply` for a named pair, directory `sync`) with a
+  prompted or `--every` schedule; no root anywhere; `pushframe schedule
+  list` shows installed jobs with next-run times (from `systemctl list-timers`).
+- [ ] **TMR-02**: `pushframe schedule remove <job>` uninstalls cleanly
+  (units + timer state); installed units are named `pushframe-<job>.service/.timer`
+  and never collide with system units.
+- [ ] **TMR-03**: unattended correctness: a scheduled run uses only
+  stored configuration (no prompts), honors SAFE-02's removal threshold
+  (a run that would exceed it **skips and logs** rather than fails the unit),
+  writes a per-job log (`~/.local/state/pushframe/<job>.log`), and the
+  docs cover `loginctl enable-linger` for headless machines (venus).
+
+### Multi-frame (MTF — GSF-01 closed)
+
+- [ ] **MTF-01**: named **album↔frame mappings** live in config: one album
+  may mirror to N frames and one frame may receive from N albums
+  (`pushframe config` manages them; `--pair <name>` selects one,
+  `--all` selects every pair).
+- [ ] **MTF-02**: `google-sync` resolves a pair the same way it resolves the
+  current single pair today (dry-run default, `--apply` gated, SAFE-01..04
+  per pair); **state is per-pair** — the manifest and staging cache are
+  sharded by pair so two pairs never share dedupe memory.
+- [ ] **MTF-03**: the write budget is **account-wide and shared** across
+  pairs within one run (`--all`), preserving SAFE-02 semantics at account
+  level; per-pair reports stay exact (pairs list what they did, and a
+  skipped pair never blocks the others).
+
+### Preflights & error quality (PRF)
+
+- [ ] **PRF-01**: commands with machine prerequisites check them up front
+  and fail with per-item remedies — `google-link` (playwright package,
+  Chrome/Chromium, profile dir) ships in 5.1's first cut (already
+  implemented on master), extended to: `google-sync` (vault present),
+  `schedule` (systemd user session available, `loginctl` linger status),
+  and `sync`/`push` (target dir exists/contains images).
+- [ ] **PRF-02**: no user-facing command may end in an unhandled traceback
+  for a foreseeable condition (missing module, missing browser, missing
+  vault, ambiguous frame, multi-arch notice): each maps to a named,
+  one-screen error with the next action. A test sweep asserts the
+  traceback-free contract for the documented failure modes.
+
+## Non-Goals
+
+| Feature | Reason |
+|---------|--------|
+| OS keyring storage (gnome-keyring/Secret Service) | headless servers (venus) lack a keyring session; file-0600 token is the contract, keyring is a later nicety |
+| Encrypting config.json with a user passphrase | circularity (where does the passphrase live?); token-first removes the high-value secret anyway |
+| Cron support | systemd user timers are the modern path; cron adds a second code path for no new capability |
+| Real deletion exposure on the Google verb | unchanged posture from v2.0/v4.0; hide-not-delete stays |
+| Many-to-many with per-pair schedules | each pair is its own scheduled job — same capability, simpler model |
+
+## Traceability
+
+Every v5.1 requirement maps to exactly one phase; numbering continues from
+Phase 22.
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| CFG-01..04 | Phase 23 | Pending |
+| SEC-01..03 | Phase 24 | Pending |
+| PRF-01..02 | Phase 24 | Pending |
+| MTF-01..03 | Phase 25 | Pending |
+| TMR-01..03 | Phase 25 | Pending |
+
+**Coverage:** v5.1 requirements: 14 total — no orphans, no double-mapping.

pushframe-5.0.5/.planning/ROADMAP.md

@@ -0,0 +1,105 @@
+# pushframe Roadmap — v5.1 Operations: Config, Sessions, Multi-frame & Scheduling
+
+**Defined:** 2026-09-29
+**Ships when:** a fresh machine goes from `apt install pushframe` to a
+scheduled, unattended, multi-frame Google mirror with **zero** hand-edited
+config files and **zero** stored passwords.
+
+## Milestone Goal
+
+Make pushframe *operable* the way it is *installable*: one conversational
+command (`pushframe config`) to set everything up, password-free sessions
+(token-first), `pushframe schedule` for root-less systemd user timers,
+named album↔frame mappings with per-pair mirror state, and preflights that
+always fail with a remedy.
+
+## Phases
+
+### Phase 23: Config Wizard & Precedence (CFG-01..04)
+
+**Goal**: `pushframe config` replaces env-var archaeology — interactive,
+masked, validated, `0600`; env vars keep working; `show` prints effective
+config with sources; `import` swallows an existing `.env`.
+
+**Success Criteria**:
+
+1. On a fresh machine, `pushframe config` → `pushframe status` works with
+   no env vars set at all (file-only path), verified in a clean container.
+2. With env vars set, they override the file — proven by a test that flips
+   both and asserts which value each command sees.
+3. `config show` never prints a secret value (redaction test); `config
+   import` on a real `.env` reproduces the same effective config as the
+   env-var path (golden diff test).
+
+**Depends on**: nothing (master already carries the google-link preflights
+that started this work).
+
+### Phase 24: Token-First Sessions & Preflight Sweep (SEC-01..03, PRF-01..02)
+
+**Goal**: the password is used once at login and never stored; the token
+drives every subsequent command with transparent re-login on expiry; the
+preflight pattern from google-link covers every command's machine
+prerequisites; no foreseeable condition ends in a traceback.
+
+**Success Criteria**:
+
+1. `pushframe config` + login → `~/.config/pushframe/` contains a token,
+   no password, mode 0600 (file-content test).
+2. A token-expiry simulation (mocked 401) transparently re-logins once and
+   retries the request; a second consecutive failure surfaces the login
+   error (no loops).
+3. The traceback-free sweep passes: every documented foreseeable failure
+   mode maps to a named error with a remedy (parametrized test).
+
+**Depends on**: Phase 23 (config file is where the token lives).
+
+### Phase 25: Multi-frame Mappings & systemd User Scheduling (MTF-01..03, TMR-01..03)
+
+**Goal**: GSF-01 and GSF-02 close — named album↔frame pairs (N:M),
+per-pair mirror state with an account-wide shared write budget, and
+`pushframe schedule` installing systemd **user** timers that run pairs
+unattended (SAFE-02 skips-and-logs, per-job logs, linger documented for
+headless hosts like venus).
+
+**Success Criteria**:
+
+1. Two pairs (one album → two frames) sync in one `--all` run, each with
+   its own manifest/cache shard, the shared budget capping the total, and
+   per-pair reports exact (container + fake-API proof).
+2. `schedule add/list/remove` round-trips units in
+   `~/.config/systemd/user/` (unit-content assertions in a container with
+   systemd available); a scheduled google-sync run is prompt-free and
+   logs to `~/.local/state/pushframe/<job>.log`.
+3. SAFE-02 behavior under scheduling: a pair whose plan exceeds the
+   removal threshold is skipped-and-logged, the unit exits 0, and the
+   other pairs still run.
+
+**Depends on**: Phase 24 (scheduled runs read token sessions, not
+passwords; preflights guard scheduled contexts).
+
+## Progress
+
+**Execution Order:** 23 → 24 → 25
+
+| Phase | Plans Complete | Status | Completed |
+|-------|----------------|--------|-----------|
+| 23. Config Wizard & Precedence | 0/? | Not started | - |
+| 24. Token-First Sessions & Preflight Sweep | 0/? | Not started | - |
+| 25. Multi-frame & systemd User Scheduling | 0/? | Not started | - |
+
+## Requirement Coverage (v5.1)
+
+| Phase | Requirements | Count |
+|-------|--------------|-------|
+| 23 | CFG-01..04 | 4 |
+| 24 | SEC-01..03, PRF-01..02 | 5 |
+| 25 | MTF-01..03, TMR-01..03 | 6 |
+| **Total** | | **15 / 15** |
+
+No orphaned requirements; no requirement mapped to more than one phase.
+
+## Backlog
+
+- Yank 5.0.0 from PyPI (empty-page release, superseded by 5.0.3).
+- OS keyring token storage (Secret Service) as an optional backend.
+- Ubuntu 26 runner observation after 2026-10-19 (deb job toolchain).

pushframe-5.0.5/.planning/STATE.md

@@ -0,0 +1,22 @@
+# pushframe — State
+
+**Milestone:** v5.1 — Operations: Config, Sessions, Multi-frame & Scheduling
+**Started:** 2026-09-29
+
+## Current Position
+
+Phase: 23 — VERIFIED (passed)
+Current Plan: 23-01 complete
+Total Plans in Phase: 1
+Status: Verified — next: phase 24 (Token-First Sessions & Preflight Sweep)
+
+## Milestone Roadmap (v5.1, Phases 23-25)
+
+- [x] Phase 23 — Config Wizard & Precedence (CFG-01..04)
+- [ ] Phase 24 — Token-First Sessions & Preflight Sweep (SEC-01..03, PRF-01..02)
+- [ ] Phase 25 — Multi-frame Mappings & systemd User Scheduling (MTF-01..03, TMR-01..03)
+
+## Completed Milestones
+
+- v4.0 — Local Google Photos Album Sync (2026-09-29)
+- v5.0 — Distribution & Rename: pushframe packages (2026-09-29)

pushframe-5.0.3/.planning/REQUIREMENTS.md → pushframe-5.0.5/.planning/milestones/v5.0-REQUIREMENTS.md

@@ -1,3 +1,12 @@
+# Requirements Archive: v5.0 v5.0
+
+**Archived:** 2026-09-29
+**Status:** SHIPPED
+
+For current requirements, see `.planning/REQUIREMENTS.md`.
+
+---
+
 # Requirements: Aura Frames Python Client — v5.0 Distribution & Rename: pushframe packages
 
 **Defined:** 2026-09-29

pushframe-5.0.5/.planning/phases/23-config-wizard-precedence/23-01-PLAN.md

@@ -0,0 +1,157 @@
+---
+phase: 23-config-wizard-precedence
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - pushframe/utils/settings.py
+  - pushframe/config_store.py
+  - pushframe/cli.py
+  - tests/test_settings_resolution.py
+  - tests/test_config_store.py
+  - tests/test_config_wizard.py
+autonomous: true
+requirements: [CFG-01, CFG-02, CFG-03, CFG-04]
+
+estimate:
+  tokens: 55000
+  raw_tokens: 42000
+  tasks: 3
+  confidence: medium
+
+must_haves:
+  truths:
+    - "settings.py resolves every settings name as config-file → env var → built-in default at access time (PEP 562 __getattr__), importers unchanged, offline suite hermetic"
+    - "~/.config/pushframe/config.json (0600, atomic write, versioned schema) stores email, auth_token, default_frame, debug, optional settings overrides, and a reserved pairs key; nothing is written when the wizard's login test fails"
+    - "pushframe config (tty-guarded wizard) walks email → masked password → live login → store; pushframe config show prints the effective config with secrets redacted and per-key sources; import migrates a .env without storing env-resolved keys; set/get/path exist and unknown keys fail listing known keys"
+
+<objective>
+Turn env-var archaeology into a conversation: dynamic settings resolution
+with locked precedence, the 0600 config.json store, and the `pushframe
+config` command family (wizard, show, import, set/get, path) — importers
+untouched, suite hermetic.
+</objective>
+
+<execution_context>
+@~/.claude/gsd-core/workflows/execute-plan.md
+@~/.claude/gsd-core/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/phases/23-config-wizard-precedence/23-CONTEXT.md
+@.planning/phases/23-config-wizard-precedence/23-RESEARCH.md
+@pushframe/utils/settings.py
+@pushframe/google/manifest.py
+</context>
+
+<tasks>
+
+<task type="tdd">
+  <name>Task 1: dynamic settings resolution + config store (CFG-02, D-01/D-02)</name>
+  <files>pushframe/utils/settings.py, pushframe/config_store.py, tests/test_settings_resolution.py, tests/test_config_store.py</files>
+  <read_first>
+    - pushframe/utils/settings.py (the constants being replaced + _env)
+    - pushframe/google/manifest.py (_atomic_write pattern to mirror)
+    - .planning/phases/23-config-wizard-precedence/23-RESEARCH.md (R1/R2/R3)
+  </read_first>
+  <action>
+1. RED tests/test_settings_resolution.py: with a tmp config.json providing
+   LOCALE=fr-FR and env unset → `settings.LOCALE == "fr-FR"`; env set → env
+   wins; neither → the built-in default; unknown name → AttributeError with
+   the known-keys list; env-shadowing helper
+   `shadowed_keys(values) -> list[str]` reports which keys env currently
+   overrides (D-04 warning source).
+2. GREEN: rewrite settings.py with a DEFAULTS table (name → default),
+   module `__getattr__` implementing config → env → default (config read
+   via config_store.load()), keep `_env` for compatibility, add
+   `known_keys()` and `shadowed_keys()`. Importers unchanged (the suite
+   proves it).
+3. RED tests/test_config_store.py: load/save round-trip; save writes 0600
+   atomically (tmp+rename); schema version key; unknown top-level keys
+   fail loud on load (the manifest pattern); reserved "pairs" dict accepted
+   (empty) for phase 25.
+4. GREEN: pushframe/config_store.py — CONFIG_PATH default
+   ~/.config/pushframe/config.json, load()/save(dict)/update(**kw),
+   os.open 0600 + atomic rename, schema version 1, key whitelist
+   (email, auth_token, default_frame, debug, settings, pairs, version).
+  </action>
+  <acceptance_criteria>
+    - All three contracts green; importer files untouched (git diff scope)
+    - config.json created 0600; corrupt file fails loud naming the path
+    - Offline suite stays green (settings importers untouched)
+  </acceptance_criteria>
+  <verify>
+    <automated>uv run --extra dev pytest tests/test_settings_resolution.py tests/test_config_store.py -q 2>&1 | tail -1 | grep -qE "[0-9]+ passed"</automated>
+    <fails_when>resolution order wrong, 0600/atomicity missing, or suite regression</fails_when>
+  </verify>
+</task>
+
+<task>
+  <name>Task 2: the config command family (CFG-01/03/04)</name>
+  <files>pushframe/cli.py, tests/test_config_wizard.py</files>
+  <read_first>
+    - pushframe/cli.py (subparser wiring + run_status's credential check pattern)
+    - .planning/phases/23-config-wizard-precedence/23-RESEARCH.md (R4/R5)
+  </read_first>
+  <action>
+1. `pushframe config` wizard (tty-guarded): existing config → show email
+   redacted, Enter keeps; email prompt (shape check); getpass password;
+   LIVE login via the existing Aura seam; success → store email +
+   user.auth_token (+ optional default frame from get_frames(), debug);
+   failure → print the API message, write NOTHING, return 1. Before
+   saving, warn listing settings.shadowed_keys() (D-04).
+   (D-03 order: credentials first + login-tested BEFORE anything is
+   stored; optional questions only after the login succeeds.)
+2. `config show`: effective config (resolution at access), secrets
+   redacted to `***` + per-key source (file/env/default) — CFG-02.
+3. `config import [--file .env]`: parse KEY=VALUE, map PUSHFRAME_*/AURA_*
+   prefixes onto settings names, store only keys NOT env-resolved now,
+   print the key → source table (CFG-03).
+4. `config path` prints the path; `config set <key> <value>` /
+   `config get <key>`: known-keys validation, unknown fails with the
+   list (CFG-04); `set` refuses auth_token/email (wizard-only keys).
+  </action>
+  <acceptance_criteria>
+    - Wizard writes nothing on failed login (file-content assertion)
+    - `config show` output never contains a token/password value
+    - import on a fixture .env reproduces the env-path effective config
+    - non-tty wizard with missing input exits 1 with a message
+  </acceptance_criteria>
+  <verify>
+    <automated>uv run --extra dev pytest tests/test_config_wizard.py -q 2>&1 | tail -1 | grep -qE "[0-9]+ passed"</automated>
+    <fails_when>secrets leak, writes on failure, or precedence inversion</fails_when>
+  </verify>
+</task>
+
+<task>
+  <name>Task 3: docs + suite + changelog</name>
+  <files>README.md, docs/CLI.md, CHANGELOG.md</files>
+  <read_first>
+    - README.md (Environment Variables section gains a Config file note)
+  </read_first>
+  <action>
+1. README: "Configuration" — the file, the wizard, the precedence line
+   (env > file > default), pointer that env vars remain supported.
+2. docs/CLI.md: `config` command reference (subcommands, exit codes).
+3. CHANGELOG [Unreleased]: Added entries (wizard, store, precedence).
+4. Full offline suite green.
+  </action>
+  <acceptance_criteria>
+    - README documents precedence + wizard; CLI.md documents config
+    - CHANGELOG [Unreleased] carries the feature
+    - suite ≥ 411 passed
+  </acceptance_criteria>
+  <verify>
+    <automated>grep -q "config" docs/CLI.md && grep -q "env var > config file\|env > file" README.md && grep -q "config" CHANGELOG.md && uv run --extra dev pytest -q -m "not live" 2>&1 | tail -1 | grep -qE "passed"</automated>
+    <fails_when>missing docs or suite failure</fails_when>
+  </verify>
+</task>
+
+</tasks>
+
+## Verification Criteria (plan-level)
+
+1. Precedence proven: file → env → default, importers unchanged.
+2. Wizard: login-tested, nothing-on-failure, 0600, shadowing warning.
+3. show/import/set/get/path all present with redaction guarantees.

pushframe-5.0.5/.planning/phases/23-config-wizard-precedence/23-01-SUMMARY.md

@@ -0,0 +1,70 @@
+# Plan 23-01 Execution Summary — Dynamic config resolution + `pushframe config` (CFG-01..04)
+
+**Phase:** 23-config-wizard-precedence
+**Date:** 2026-09-29
+**Status:** Complete — suite **426 passed** (was 420 before the phase; +6 wizard tests, +8 resolution/store tests, 2 legacy alias asserts updated to the dynamic contract)
+**Commits:** `936a2c4` (T1 dynamic resolution + config_store) · `acd3ba1` (T3 docs) · T2 wizard shipped in the T1→T2 working commit on this branch
+
+## What Shipped
+
+- **Dynamic settings resolution (D-01/D-04, CFG-02)** — `settings.py` rewritten
+  around PEP 562 module `__getattr__`: every `settings.X` access resolves live as
+  **environment → config file (`~/.config/pushframe/config.json`) → DEFAULTS
+  table**. All existing importers kept their attribute-style reads (the 411→420
+  regression passed byte-for-byte on defaults); `s3client`/`sqsclient` converted
+  from frozen `from settings import X` copies to module-attribute reads so
+  long-running processes see updates.
+- **`config_store.py` (D-02)** — 0600 JSON store, atomic writes (tmp + rename),
+  known-key whitelist (fail-loud on unknown keys), schema-versioned, `"pairs"`
+  key reserved for phase 25 (multi-frame). Reads `settings.CONFIG_PATH`
+  dynamically (module import, not from-import) so tests and the wizard share
+  one path truth.
+- **The `config` family (D-03, CFG-01/03/04)** — wired into the CLI parser and
+  dispatch:
+  - `pushframe config` — wizard: email → hidden password → **real API login
+    before anything is written** (fail = zero writes); stores email +
+    `auth_token`; optional questions afterwards; refuses non-tty stdin for the
+    interactive path (scheduled jobs never hang on a prompt).
+  - `config show` — every setting with effective value (secrets `***`) and
+    its source (`env`/`file`/`default`) + explicit env-shadow warnings.
+  - `config import FILE` — adopts `.env`-style files; skips env-provided keys
+    (reported), validates against the whitelist.
+  - `config set/get/path` — single-key direct access; `get` reflects true
+    precedence.
+- **Docs (T3)** — README gets a wizard-first *Configuration* section (env vars
+  folded into an override `<details>`); `docs/CLI.md` gets a full `config`
+  command section + precedence-aware env-var intro; CHANGELOG `[Unreleased]`
+  carries Added/Changed entries.
+
+## Broken-and-fixed along the way
+
+- CHANGELOG had been corrupted by the session interruption (sections out of
+  order: Unreleased/5.0.4/5.0.3 stuck *after* 5.0.0; 5.0.4 content duplicated
+  inside its own block). Rewritten cleanly in Keep-a-Changelog order,
+  deduplicated — no content lost.
+- `config_store` initially froze `CONFIG_PATH` via from-import (test
+  monkeypatch invisible) → module-attribute read.
+- `_bool_env` signature drifted from the historical `default=` keyword →
+  restored (12 budget tests green again).
+- AWS from-imports froze values at import time → dynamic access (matches the
+  phase-19 MOD-02 intent; two legacy alias asserts updated accordingly).
+
+## Live proofs
+
+- Wrong-password login against the real API raises
+  (`RateLimitError … HTTP 475`, the account's current Aura-side lockout) and
+  writes **no config.json** — the D-03 "nothing written on failed login"
+  contract, verified live. A successful-login wizard run was not repeated
+  against the real API to avoid worsening the lockout; the seam
+  (`_wizard_login`) is exactly the tested `Aura.login` path.
+
+## Must-have truths check (plan 23-01)
+
+| Truth | Status |
+|---|---|
+| Env/file/default precedence at access time | ✅ PEP 562 + DEFAULTS table (8 tests) |
+| config.json 0600, atomic, whitelist, schema-versioned | ✅ config_store + tests |
+| Wizard tests login before writing; fail = zero writes | ✅ 6 tests + live negative proof |
+| `config show` reports source per key + shadows | ✅ implemented + tested |
+| Import skips env-provided keys | ✅ tested (env-shadow contract) |
+| Existing readers unchanged | ✅ 426 passed incl. all pre-phase tests |

pushframe-5.0.5/.planning/phases/23-config-wizard-precedence/23-CONTEXT.md

@@ -0,0 +1,68 @@
+# Phase 23: Config Wizard & Precedence — Context
+
+**Gathered:** 2026-09-29
+**Status:** Ready for planning
+**Provenance:** compiled from REQUIREMENTS CFG-01..04, a full read of the
+current config plumbing (`pushframe/utils/settings.py`, its 7+ importers,
+`cli.py`'s env reads), and the operator's design decisions taken at the
+discuss checkpoint (2026-09-29).
+
+## Current state (probe facts)
+
+- `pushframe/utils/settings.py` exposes ~15 **module constants evaluated
+  at import** via the `_env(*names)` helper: PUSHFRAME_* primary, AURA_*
+  legacy fallback (IDN-04), hard-coded defaults last.
+- Importers do `from pushframe.utils import settings` and read
+  `settings.LOCALE`, `settings.AURA_API_BASE_URL`, budget constants, etc.
+  — none import `settings` as mutable state they replace.
+- Credentials today: `PUSHFRAME_EMAIL` / `PUSHFRAME_PASSWORD` read in
+  `pushframe/aura.py` (login) and `cli.py` (status health check prints
+  set/NOT SET only).
+- Existing JSON in `~/.config/pushframe/`: `google-cookies.json` (0600
+  vault), `google-manifest.json` (0600), budget file. A config.json sits
+  naturally in that family.
+- The deb/wheel ships no `python-dotenv` auto-import for user shells
+  (`.env` is loaded by `main()` via `load_dotenv()` — cwd-relative, a
+  known fragility the file-config supersedes for humans).
+
+## Design decisions (operator, 2026-09-29)
+
+- **D-01:** Dynamic resolution — `settings.py` keeps its public names but
+  each becomes a *resolved-at-access* value with precedence
+  **config file → env var → built-in default**; importers stay untouched.
+  `config set` affects the next process and any re-read; no stale
+  import-time snapshot. Implementation must keep the offline test suite
+  hermetic (tests patch the file path / env, never the network).
+- **D-02:** JSON — `~/.config/pushframe/config.json`, mode 0600, stdlib
+  `json` only — same family as the vault/manifest. The MTF-01 pairs
+  (phase 25) will live there as a dict.
+- **D-03:** Wizard order: credentials first, login-tested — email →
+  password (getpass, masked) → **live login test** → on success store
+  email + the returned `auth_token` (SEC-01 lands in phase 24; phase 23
+  already stores the token since the API hands it back) → optional
+  questions (default frame — listed from a real `get_frames` when
+  credentials work —, debug). Login failure ⇒ clear message, **nothing
+  is written**.
+- **D-04:** Precedence (locked): env var > config file > default —
+  Rationale: 12-factor; CI/scripts keep working unchanged; the file is
+  human comfort. The wizard warns when an env var would shadow the file
+  value it just wrote (the venus lesson: silent shadowing is the trap).
+
+## Non-goals for this phase
+
+- Token *expiry/re-login* semantics (phase 24, SEC-02).
+- OS keyring backends, config encryption (v5.1 non-goals table).
+- MTF pairs schema beyond reserving the `"pairs": {}` key in the file
+  schema (phase 25).
+
+## Operator steps
+
+None — everything is in-repo; the phase ships in the next release.
+
+## Discretion areas (executor)
+
+- Exact wizard prompt wording/order of optional questions.
+- Whether `config show` reads settings lazily per key or snapshots
+  (recommend lazy — matches D-01).
+- Test seam choice: fixture writing a temp config.json + monkeypatched
+  path constant (existing pattern in tests/test_migration.py).