Carlos Florêncio
86 lines
3.3 KiB
Markdown
86 lines
3.3 KiB
Markdown
---
|
|
id: "02-document-database-path"
|
|
title: "Document the SQLite backup location"
|
|
status: done
|
|
wave: 2
|
|
depends_on: ["01-backend-database-path"]
|
|
plan: "plan.md"
|
|
spec: "../../specs/system-page/spec.md"
|
|
---
|
|
|
|
# Task 02: Document the SQLite backup location
|
|
|
|
## Intent
|
|
|
|
Replace the documented custom-path limitation with the corrected System behavior. Keep the legacy-snapshot and home-storage boundaries explicit.
|
|
|
|
## Acceptance
|
|
|
|
- Public references state that SQLite snapshots use `backups/` beside the configured database file.
|
|
- Restore documentation names `<configured-database-path>.new` and the exact configured destination.
|
|
- Restore documentation explains that scheduling, active executions, and database-backed workers stop, the SQLite pool closes, replacement is rollback-safe, PostgreSQL restore is rejected, and an immediate restart is required.
|
|
- Public and agent guidance states that old misrouted snapshots do not move automatically.
|
|
|
|
## Files likely touched
|
|
|
|
- `docs/public/cli.md`
|
|
- `docs/public/configuration.md`
|
|
- `docs/public/operations.md`
|
|
- `docs/public/feature-status.md`
|
|
- `docs/public/use-kandev.md`
|
|
- `apps/backend/AGENTS.md`
|
|
- `apps/web/components/settings/system/restore-dialog.tsx`
|
|
- `apps/web/src/locales/*/system.json`
|
|
|
|
## Dependencies
|
|
|
|
Task 01 must establish the final backend behavior.
|
|
|
|
## Parallelism
|
|
|
|
Sequential. These pages document the result of Task 01.
|
|
|
|
## Inputs
|
|
|
|
- Spec: `docs/specs/system-page/spec.md`, configured database path scenarios and persistence guarantees.
|
|
- Plan: `plan.md`, public documentation and risk sections.
|
|
- Docs type: `configuration.md` and `cli.md` are references. `operations.md` is a how-to guide. `feature-status.md` is a reference. `use-kandev.md` is a tutorial.
|
|
|
|
## Verification
|
|
|
|
Run the focused terminology search and public-doc validators:
|
|
|
|
```bash
|
|
rg -n 'KANDEV_DATABASE_PATH|data/backups|database path|backup caveat' docs/public apps/backend/AGENTS.md
|
|
node --test scripts/validate-public-docs.test.mjs
|
|
node scripts/validate-public-docs.mjs
|
|
git diff --check
|
|
```
|
|
|
|
## Output contract
|
|
|
|
Report each changed public page and its primary documentation type. Report validator results and remaining intentional `data/backups` references. Update this task and `plan.md` in the same conversation.
|
|
|
|
## Restore safety remediation
|
|
|
|
- Updated the public and backend guidance for checkpoint validation, quarantine rollback, PostgreSQL rejection, and the closed-pool restart requirement.
|
|
- Updated the localized restore success dialog to invoke the existing restart flow and to provide manual quit-and-relaunch guidance.
|
|
|
|
## Results
|
|
|
|
- Public docs updated:
|
|
- `docs/public/cli.md` (reference)
|
|
- `docs/public/configuration.md` (reference)
|
|
- `docs/public/operations.md` (how-to and recovery guide)
|
|
- `docs/public/feature-status.md` (reference)
|
|
- `docs/public/use-kandev.md` (tutorial)
|
|
- Backend guidance updated: `apps/backend/AGENTS.md` now names the configured
|
|
SQLite path and its sibling backup directory.
|
|
- `rg -n 'KANDEV_DATABASE_PATH|data/backups|database path|backup caveat'
|
|
docs/public apps/backend/AGENTS.md` passed. Remaining `data/backups`
|
|
references describe the default path, development safety snapshots, or the
|
|
home-based System Status walk.
|
|
- `node --test scripts/validate-public-docs.test.mjs` passed 61 tests.
|
|
- `node scripts/validate-public-docs.mjs` validated 41 published docs pages.
|
|
- `git diff --check` passed.
|