Repository navigation
docs: remove retired docs and correct stale instructions - #1410
Conversation
A read-only audit checked every doc against master. This removes what only describes retired things and corrects what now tells people to do something impossible or unsafe. Removed: the Sungrow observe pilot (lives in device-drivers), the July failed-rollback runbook for the old Docker line, ADR 0005 (superseded, Home Link gone) and the CalDAV note, folded into upgrade-from-legacy. Corrected: a manual install that bypassed the release slots, rollback through an update UI native does not have, a restore revert path that Core refuses, the support dump method, the setup guides' username (the installer refuses an account named ftw), Nova claiming on native, the storage description (plain SQLite buckets, no Parquet), the Python optimizer and sidecar, the old release cadence, and a dated roadmap review condensed to what still steers work. Code pointers to removed docs are fixed, and the missing-worker error no longer tells operators to run a sidecar that is gone. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MuerPFZFG88kgu8sWVHeq7
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: a4d8ceb556
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| // `exec: ... not found in $PATH`. | ||
| var errOptimizerWorkerMissing = errors.New( | ||
| "optimizer worker interpreter not found on PATH; this core build has no bundled Python optimizer — run the ftw-optimizer sidecar (see docs/self-update.md)") | ||
| "optimizer worker not found; the Energyplan worker from the release package is missing, so the built-in Go planner is used") |
There was a problem hiding this comment.
When the worker is missing on a batteryless site, a site with multiple storages/EVs, or one with per-storage efficiencies, coreDPModelError prevents the Go DP fallback and service.go keeps the previous plan instead. This error is exposed through component health and support reports, so the new text tells operators that the built-in planner is being used even though no new plan was produced; keep the transport error neutral and report fallback use only after Service actually selects it.
AGENTS.md reference: AGENTS.md:L22-L25
Useful? React with 👍 / 👎.
1 participant
Why
The owner asked to clear out documentation that is no longer current. A read-only audit checked every Markdown file against
master: code, scripts, workflows and inbound links. It found docs describing retired things (the Docker updater as current, Parquet history, the Python optimizer, Home Link, CalDAV, the Pi image) and some that tell people to do something impossible or unsafe on native 0.x.Removed
docs/sungrow-observe-pilot.md: duplicatessrcfl/device-driverspackages/v1/sungrow/PILOT.md. No inbound links.docs/recover-failed-rollback.sv.md: a one-off runbook for the July old-line incident fixed by Fix rollback data safety and legacy recovery #583. The operations pointer and the brand allowlist entry go with it.docs/adr/0005-outbound-site-link.md: superseded by ADR 0006, and Home Link is gone, like ADRs 0001–0004 before it. ADR 0006 now names it without a link.docs/caldav-integration.md: its one live instruction (move calendar events to ready-by schedules; acaldavsection is ignored with a warning) now sits inupgrade-from-legacy.md.docs/superpowers/plans/…file that does not exist.Unsafe or impossible instructions, corrected
linux-packages.md: the manual/opt/ftw/ftw+ftw.serviceinstall bypassed the release slots (ADR 0007 decision 14). It now points to the installer.operations.md: the installer came frommasterwith an old tag. It now uses the same-tag installer.operations.mdsaid "roll back through the update UI" and "pin the previous image tag". It now namesftw rollback, the launcher's offline rollback, andFTW_VERSIONfor Docker 0.x.backup-and-restore.md, the revert path was/var/lib/.ftw-pre-restore-…, whichRevertContentsrefuses. It is now/var/lib/ftw/.ftw-pre-restore-…. A native restore section was added, andrestore-full-backup.shis marked old line (it needsdocker-compose.yml).native-beta.mdsaidPOST /api/support/dump; the route isGET.ftw, which the installer refuses. "Or updating" is dropped from the protected-routes hint../ftw nova-claimdoes not work on native, whereftwonPATHis the CLI. The docs now run the release's Core binary asftwin/var/lib/ftwand restart the service. This is derived fromnova_claim.go; not run against Nova.FTW_API_TOKENnow has native (systemd drop-in) and Docker 0.x (environment:) instructions; only the old compose passed it.Stale descriptions, updated
architecture.md: storage is plain SQLite buckets (10 s for 7 days, 1 min for 90 days, 1 h for 5 years, plus the ledger). No Parquet is written, and diagnostics are kept 7 days. Releases are the package, the launcher and slots; the sidecar belongs to the frozen line. The CalDAV example is removed.development.md: the Python optimizer, venv and 3.11 text is gone. Make targets are checked against the Makefile, and the root compose is described as the frozen line, with Docker 0.x indeploy/docker.operations.mdandbackup-and-restore.md: lead with native, then Docker 0.x, with the older Docker line clearly marked. The Swedish backup summary is rewritten aroundftw backup.self-update.md: theftwctl.py migrate-nativepilot is labelled as not the user migration path.safety.md,device-repository.md(Settings → Devices, not the Update Center), and ADR 0007 (no longer "until implemented";ftw update --retryinstead of an unimplemented--backup-dir).Code (patch changeset)
FTW_UPDATER_SOCKETin self-update.md are fixed.Left alone
docs/ftwdb-shadow.md(still describes DuckDB as primary) is touched by open docs: keep one agent guide and correct the retired FTWDB note #1364, which has right of way.upgrade-from-legacy.mdandupgrade-paired-release.mdstay: old boxes and the root compose files carry their URLs.Evidence
#anchorin all Markdown files (except CHANGELOG) finds 0 broken.LC_ALL=C.UTF-8). Under my localsvlocale,commcomplains about sort order.check-no-planning-docs.shandnpm test(630) pass, and so dogo test ./internal/mpc ./internal/control.🤖 Generated with Claude Code
https://claude.ai/code/session_01MuerPFZFG88kgu8sWVHeq7