residual/.agent

Watch

Fork 0

Cleanup stale documents across all repos #12

New issue

Open

opened 2026-07-21 19:29:17 +00:00 by agent · 4 comments

agent commented

2026-07-21 19:29:17 +00:00

Member

Plan: Cleanup stale documents across all repos

Goal

Audit and clean up stale documentation across the residual workspace. Some documents are entirely superseded by the core/ consolidation and should be deleted. Others have specific stale sections that need rewriting.

Background

The great core/ consolidation happened months ago: all core binaries (res, res-init, res-console, res-sh, res-login, res-edit) and shared libraries were folded into the single core/ Go module. Old per-app repos (init/, console/, shell/, auth/, res/, editor/) no longer exist. Many documents still reference the old layout, old binary names (residual-*), old package paths (core/proc/ instead of core/lib/proc/), and old build instructions.

Documents to DELETE

1. `CLAUDE.md` (workspace root)

Why: Entirely superseded by AGENTS.md. Contains pre-core repo layout, old binary table, old build instructions (cd init && go build ./cmd/res-init), old .agents/ reference, old dependency graph.
Action: Delete file.

2. `.agent/notes/architecture.md`

Why: Lists init/, console/, shell/, auth/, res/ as separate repos with their own go.mod. Says core/ has no binaries. Entirely wrong.
Action: Delete file.

Documents to REWRITE

3. `docs/init-design.md` — Major rewrite

Old architecture diagram shows separate repos (init/, login/, console/, editor/, shell/)
Old package paths: core/proc/, core/ipc/, core/lock/, core/script/ → should be core/lib/proc/, etc.
Old extraction scope table references console/script/lua.go (doesn't exist)
Lifecycle diagram references core/lock, core/ipc, core/proc
Design decisions table references core/script/, core/lock/
Keep: Service file names (residual-init.service, /etc/init.d/residual-init), PAM names, runit names — these are correct by design.

4. `docs/os/os.md` — Major rewrite

Old binary names: residual-login, residual-sh, residual-console → res-login, res-sh, res-console
Persistence CLI described as residual with subcommands → should be res-os
Old planning notes: init/residual-init → to be renamed residual-initramfs (verify if this happened)

5. `docs/architecture.md` — Minor rewrite

4 package path references: core/script/ → core/lib/script/, core/proc/ → core/lib/proc/

6. `docs/design/tooling.md` — Minor rewrite

Old per-repo build commands (cd init && go build ./cmd/res-init) → single cd core && go build ./cmd/...

7–10. Console docs — Title/header fixes

docs/keymap.md line 41: residual-console → res-console
docs/console/console.md line 1: residual-console → res-console
docs/console/console-design.md line 1: residual-console → res-console
docs/console/scripting.md line 1: residual-console → res-console

11. `docs/design/aesthetic.md` — Minor fix

Line 183: residual-console → res-console

12–14. `core/.agent/claude/` files

handoff.md: Binary table shows old separate repos → update to core/ single module
notes.md: Claims top-level dirs are independent repos, stale editor/sidebar.go path → update
todo.md: Says res-edit exists in editor/ → update to core/cmd/res-edit

Documents to REVIEW

15. `os/README.md`

Mentions init/residual-init → to be renamed residual-initramfs. Verify if rename happened. Update or remove planning notes.

Implementation steps

Delete phase: Remove CLAUDE.md and .agent/notes/architecture.md
Fix binary names: Batch-replace residual-console → res-console, residual-edit → res-edit, residual-sh → res-sh, residual-login → res-login across all docs
Fix package paths: Batch-replace core/proc/ → core/lib/proc/, core/ipc/ → core/lib/ipc/, core/lock/ → core/lib/lock/, core/script/ → core/lib/script/, core/tui/ → core/lib/tui/
Rewrite docs/init-design.md: Update architecture diagram and all package paths
Rewrite docs/os/os.md: Update binary names, verify persistence CLI name, clean up initramfs notes
Rewrite docs/design/tooling.md: Update build commands
Fix core/.agent/claude/ files: Update repo layout descriptions
Review os/README.md: Verify initramfs hook status
Verification: go build ./... && go test ./... in core/ and extra/

Risks

docs/init-design.md is a large canonical document. Rewriting it risks introducing new errors. Consider doing it in a separate PR from the minor fixes.
Some residual-* references may be intentional (systemd service names, PAM service names, unix group names). Do not blindly replace — verify context.
core/.agent/claude/ files are agent operational memory. Rewriting them affects future agent sessions. Be careful to preserve useful warnings (e.g., "old paths like core/proc/").

Verification checklist

No file references core/proc/, core/ipc/, core/lock/, core/script/, core/tui/ as package paths
No file claims init/, console/, shell/, auth/, res/ are separate repos with their own go.mod
No file uses residual-console, residual-edit, residual-sh, residual-login as binary names (except for systemd/PAM/runit service names)
docs/init-design.md architecture diagram reflects core/ single module
docs/os/os.md uses res-os for persistence CLI
go build ./... && go test ./... passes in core/ and extra/

# Plan: Cleanup stale documents across all repos ## Goal Audit and clean up stale documentation across the residual workspace. Some documents are entirely superseded by the `core/` consolidation and should be deleted. Others have specific stale sections that need rewriting. ## Background The great `core/` consolidation happened months ago: all core binaries (`res`, `res-init`, `res-console`, `res-sh`, `res-login`, `res-edit`) and shared libraries were folded into the single `core/` Go module. Old per-app repos (`init/`, `console/`, `shell/`, `auth/`, `res/`, `editor/`) no longer exist. Many documents still reference the old layout, old binary names (`residual-*`), old package paths (`core/proc/` instead of `core/lib/proc/`), and old build instructions. ## Documents to DELETE ### 1. `CLAUDE.md` (workspace root) - **Why:** Entirely superseded by `AGENTS.md`. Contains pre-core repo layout, old binary table, old build instructions (`cd init && go build ./cmd/res-init`), old `.agents/` reference, old dependency graph. - **Action:** Delete file. ### 2. `.agent/notes/architecture.md` - **Why:** Lists `init/`, `console/`, `shell/`, `auth/`, `res/` as separate repos with their own `go.mod`. Says `core/` has no binaries. Entirely wrong. - **Action:** Delete file. ## Documents to REWRITE ### 3. `docs/init-design.md` — Major rewrite - Old architecture diagram shows separate repos (`init/`, `login/`, `console/`, `editor/`, `shell/`) - Old package paths: `core/proc/`, `core/ipc/`, `core/lock/`, `core/script/` → should be `core/lib/proc/`, etc. - Old extraction scope table references `console/script/lua.go` (doesn't exist) - Lifecycle diagram references `core/lock`, `core/ipc`, `core/proc` - Design decisions table references `core/script/`, `core/lock/` - **Keep:** Service file names (`residual-init.service`, `/etc/init.d/residual-init`), PAM names, runit names — these are correct by design. ### 4. `docs/os/os.md` — Major rewrite - Old binary names: `residual-login`, `residual-sh`, `residual-console` → `res-login`, `res-sh`, `res-console` - Persistence CLI described as `residual` with subcommands → should be `res-os` - Old planning notes: `init/residual-init` → to be renamed `residual-initramfs` (verify if this happened) ### 5. `docs/architecture.md` — Minor rewrite - 4 package path references: `core/script/` → `core/lib/script/`, `core/proc/` → `core/lib/proc/` ### 6. `docs/design/tooling.md` — Minor rewrite - Old per-repo build commands (`cd init && go build ./cmd/res-init`) → single `cd core && go build ./cmd/...` ### 7–10. Console docs — Title/header fixes - `docs/keymap.md` line 41: `residual-console` → `res-console` - `docs/console/console.md` line 1: `residual-console` → `res-console` - `docs/console/console-design.md` line 1: `residual-console` → `res-console` - `docs/console/scripting.md` line 1: `residual-console` → `res-console` ### 11. `docs/design/aesthetic.md` — Minor fix - Line 183: `residual-console` → `res-console` ### 12–14. `core/.agent/claude/` files - `handoff.md`: Binary table shows old separate repos → update to `core/` single module - `notes.md`: Claims top-level dirs are independent repos, stale `editor/sidebar.go` path → update - `todo.md`: Says `res-edit` exists in `editor/` → update to `core/cmd/res-edit` ## Documents to REVIEW ### 15. `os/README.md` - Mentions `init/residual-init` → to be renamed `residual-initramfs`. Verify if rename happened. Update or remove planning notes. ## Implementation steps 1. **Delete phase:** Remove `CLAUDE.md` and `.agent/notes/architecture.md` 2. **Fix binary names:** Batch-replace `residual-console` → `res-console`, `residual-edit` → `res-edit`, `residual-sh` → `res-sh`, `residual-login` → `res-login` across all docs 3. **Fix package paths:** Batch-replace `core/proc/` → `core/lib/proc/`, `core/ipc/` → `core/lib/ipc/`, `core/lock/` → `core/lib/lock/`, `core/script/` → `core/lib/script/`, `core/tui/` → `core/lib/tui/` 4. **Rewrite `docs/init-design.md`:** Update architecture diagram and all package paths 5. **Rewrite `docs/os/os.md`:** Update binary names, verify persistence CLI name, clean up initramfs notes 6. **Rewrite `docs/design/tooling.md`:** Update build commands 7. **Fix `core/.agent/claude/` files:** Update repo layout descriptions 8. **Review `os/README.md`:** Verify initramfs hook status 9. **Verification:** `go build ./... && go test ./...` in `core/` and `extra/` ## Risks - `docs/init-design.md` is a large canonical document. Rewriting it risks introducing new errors. Consider doing it in a separate PR from the minor fixes. - Some `residual-*` references may be intentional (systemd service names, PAM service names, unix group names). Do not blindly replace — verify context. - `core/.agent/claude/` files are agent operational memory. Rewriting them affects future agent sessions. Be careful to preserve useful warnings (e.g., "old paths like `core/proc/`"). ## Verification checklist - [ ] No file references `core/proc/`, `core/ipc/`, `core/lock/`, `core/script/`, `core/tui/` as package paths - [ ] No file claims `init/`, `console/`, `shell/`, `auth/`, `res/` are separate repos with their own `go.mod` - [ ] No file uses `residual-console`, `residual-edit`, `residual-sh`, `residual-login` as binary names (except for systemd/PAM/runit service names) - [ ] `docs/init-design.md` architecture diagram reflects `core/` single module - [ ] `docs/os/os.md` uses `res-os` for persistence CLI - [ ] `go build ./... && go test ./...` passes in `core/` and `extra/`

agent added the

tier-2-project

label

2026-07-21 19:29:19 +00:00

agent commented

2026-07-21 19:51:35 +00:00

Author

Member

Corrections from user review

1. CLAUDE.md should be REWRITTEN, not deleted

CLAUDE.md is intentionally kept as a copy of AGENTS.md for devcontainer/Claude Code context. It should be rewritten to match the current AGENTS.md (post-core consolidation), not deleted. The stale content (pre-core layout, old binary table, old build instructions) needs to be updated to the current single-module core/ layout.

2. Binary naming: `residual-login` is correct, `res-login` is wrong

The login manager has no reason to be a subcommand of the res utility. It should keep the residual- prefix:

Correct: residual-login
Wrong: res-login

This affects:

core/cmd/res-login/ — directory may need renaming, or binary output name changed
All docs referencing res-login → residual-login
AGENTS.md itself (currently says res-login)
docs/os/os.md (already uses residual-login — this was actually correct)
docs/keymap.md, docs/console/*.md, docs/design/aesthetic.md — verify if any mention res-login

Exception: Systemd/PAM/runit service names like residual-login@.service and unix group residual-init are correct by design and should NOT be changed.

3. Updated action items

REWRITE CLAUDE.md to match current AGENTS.md (single core/ module, current binary names)
VERIFY docs/os/os.md — it already uses residual-login, so it may be partially correct already
UPDATE AGENTS.md — change res-login → residual-login in binary table and all references
UPDATE core/cmd/res-login/ — rename directory or change build output to residual-login
UPDATE all other docs — change res-login → residual-login where it refers to the binary

4. Note on `residual-` vs `res-` naming

The user has clarified that residual-login is the exception. Other core binaries (res-console, res-sh, res-edit, res-init, res) correctly use the res-* prefix. Only res-login was wrong.

## Corrections from user review ### 1. CLAUDE.md should be REWRITTEN, not deleted CLAUDE.md is intentionally kept as a copy of AGENTS.md for devcontainer/Claude Code context. It should be **rewritten to match the current AGENTS.md** (post-core consolidation), not deleted. The stale content (pre-core layout, old binary table, old build instructions) needs to be updated to the current single-module `core/` layout. ### 2. Binary naming: `residual-login` is correct, `res-login` is wrong The login manager has no reason to be a subcommand of the `res` utility. It should keep the `residual-` prefix: - **Correct:** `residual-login` - **Wrong:** `res-login` This affects: - `core/cmd/res-login/` — directory may need renaming, or binary output name changed - All docs referencing `res-login` → `residual-login` - AGENTS.md itself (currently says `res-login`) - `docs/os/os.md` (already uses `residual-login` — this was actually correct) - `docs/keymap.md`, `docs/console/*.md`, `docs/design/aesthetic.md` — verify if any mention `res-login` **Exception:** Systemd/PAM/runit service names like `residual-login@.service` and unix group `residual-init` are correct by design and should NOT be changed. ### 3. Updated action items - [ ] REWRITE `CLAUDE.md` to match current `AGENTS.md` (single `core/` module, current binary names) - [ ] VERIFY `docs/os/os.md` — it already uses `residual-login`, so it may be partially correct already - [ ] UPDATE `AGENTS.md` — change `res-login` → `residual-login` in binary table and all references - [ ] UPDATE `core/cmd/res-login/` — rename directory or change build output to `residual-login` - [ ] UPDATE all other docs — change `res-login` → `residual-login` where it refers to the binary ### 4. Note on `residual-*` vs `res-*` naming The user has clarified that `residual-login` is the exception. Other core binaries (`res-console`, `res-sh`, `res-edit`, `res-init`, `res`) correctly use the `res-*` prefix. Only `res-login` was wrong.

agent commented

2026-07-21 19:52:41 +00:00

Author

Member

Additional correction: `residual-init` naming

The res-init → residual-init rename also applies:

residual-init is the system-level init daemon. It keeps the residual- prefix.
res-init is reserved for a separate future tool (not the init daemon).
All other core binaries correctly use the res-* prefix.

Files affected by `res-init` → `residual-init`

AGENTS.md — binary table says res-init
core/cmd/res-init/ — directory may need renaming or build output changed
docs/init-design.md — references res-init throughout
docs/res-init-client.md — references res-init
docs/README.md — references res-init
docs/os/os.md — verify current usage
core/internal/libs/init/ — package comments may reference binary name
core/cmd/res-demo/ — demo tool may reference res-init

Complete naming convention (confirmed)

Binary	Prefix	Reason
`residual-init`	`residual-`	System-level init daemon
`residual-login`	`residual-`	Login manager (not a `res` subcommand)
`res`	`res`	Dispatcher
`res-console`	`res-`	Console multiplexer
`res-sh`	`res-`	Shell
`res-edit`	`res-`	Editor
`res-os`	`res-`	OS builder
`res-demo`	`res-`	Dev tool
`res-theme`	`res-`	Dev tool
`res-calc`	`res-`	Extra utility
`res-code`	`res-`	Extra utility
`res-sheets`	`res-`	Extra utility

Updated action items for issue #12

REWRITE CLAUDE.md to match current AGENTS.md
UPDATE AGENTS.md — res-login → residual-login, res-init → residual-init
UPDATE core/cmd/res-login/ → residual-login (directory or build output)
UPDATE core/cmd/res-init/ → residual-init (directory or build output)
UPDATE docs/init-design.md — res-init → residual-init
UPDATE docs/res-init-client.md — res-init → residual-init
UPDATE docs/README.md — res-init → residual-init, res-login → residual-login
VERIFY docs/os/os.md — already uses residual-login, check res-init usage
UPDATE all other docs — res-login → residual-login, res-init → residual-init

## Additional correction: `residual-init` naming The `res-init` → `residual-init` rename also applies: - **`residual-init`** is the system-level init daemon. It keeps the `residual-` prefix. - **`res-init`** is reserved for a separate future tool (not the init daemon). - All other core binaries correctly use the `res-*` prefix. ### Files affected by `res-init` → `residual-init` - `AGENTS.md` — binary table says `res-init` - `core/cmd/res-init/` — directory may need renaming or build output changed - `docs/init-design.md` — references `res-init` throughout - `docs/res-init-client.md` — references `res-init` - `docs/README.md` — references `res-init` - `docs/os/os.md` — verify current usage - `core/internal/libs/init/` — package comments may reference binary name - `core/cmd/res-demo/` — demo tool may reference `res-init` ### Complete naming convention (confirmed) | Binary | Prefix | Reason | |--------|--------|--------| | `residual-init` | `residual-` | System-level init daemon | | `residual-login` | `residual-` | Login manager (not a `res` subcommand) | | `res` | `res` | Dispatcher | | `res-console` | `res-` | Console multiplexer | | `res-sh` | `res-` | Shell | | `res-edit` | `res-` | Editor | | `res-os` | `res-` | OS builder | | `res-demo` | `res-` | Dev tool | | `res-theme` | `res-` | Dev tool | | `res-calc` | `res-` | Extra utility | | `res-code` | `res-` | Extra utility | | `res-sheets` | `res-` | Extra utility | ### Updated action items for issue #12 - [ ] REWRITE `CLAUDE.md` to match current `AGENTS.md` - [ ] UPDATE `AGENTS.md` — `res-login` → `residual-login`, `res-init` → `residual-init` - [ ] UPDATE `core/cmd/res-login/` → `residual-login` (directory or build output) - [ ] UPDATE `core/cmd/res-init/` → `residual-init` (directory or build output) - [ ] UPDATE `docs/init-design.md` — `res-init` → `residual-init` - [ ] UPDATE `docs/res-init-client.md` — `res-init` → `residual-init` - [ ] UPDATE `docs/README.md` — `res-init` → `residual-init`, `res-login` → `residual-login` - [ ] VERIFY `docs/os/os.md` — already uses `residual-login`, check `res-init` usage - [ ] UPDATE all other docs — `res-login` → `residual-login`, `res-init` → `residual-init`

agent commented

2026-07-21 20:11:53 +00:00

Author

Member

Starting implementation. Build mode engaged.

agent commented

2026-07-21 20:20:16 +00:00

Author

Member

Implementation complete ✅

All changes from the stale document cleanup plan have been implemented and pushed.

Changes made

Workspace root (residual/.agent):

✅ Updated AGENTS.md — res-init → residual-init, res-login → residual-login
✅ Rewrote CLAUDE.md to match current AGENTS.md
✅ Deleted .agent/notes/architecture.md (pre-core layout)

core/ repo:

✅ Renamed cmd/res-init/ → cmd/residual-init/
✅ Renamed cmd/res-login/ → cmd/residual-login/
✅ Updated core/.agent/claude/handoff.md, notes.md, todo.md

docs/ repo:

✅ docs/init-design.md — fixed architecture diagram, dependency graph, package paths, binary names
✅ docs/os/os.md — fixed binary names (residual-sh → res-sh, residual-console → res-console, persistence CLI residual → res-os)
✅ docs/architecture.md — fixed package paths and binary names
✅ docs/design/tooling.md — fixed build commands and binary names
✅ docs/design/aesthetic.md — fixed residual-console reference
✅ docs/design/lua-scripting.md — fixed res-init references
✅ docs/keymap.md — fixed title
✅ docs/console/console.md — fixed title
✅ docs/console/console-design.md — fixed title
✅ docs/console/scripting.md — fixed title
✅ docs/res-init-client.md — fixed all res-init references
✅ docs/res-dispatcher.md — fixed res-login reference
✅ docs/README.md — fixed binary names
✅ .opencode/agents/*.md — fixed binary names in agent harness files
✅ .opencode/skills/residual/SKILL.md — fixed binary names and paths

Verification

✅ cd core && go build ./... — PASS
✅ cd core && CGO_ENABLED=1 go test ./... — PASS
✅ cd extra && go build ./... && go test ./... — PASS

Commits pushed

residual/.agent: d2d63dc — docs: update AGENTS.md binary names, delete stale architecture.md
residual/core: 99ef311 — refactor: rename cmd/res-init → cmd/residual-init, cmd/res-login → cmd/residual-login
residual/docs: 5e15a56 — docs: fix stale binary names, package paths, and build commands

## Implementation complete ✅ All changes from the stale document cleanup plan have been implemented and pushed. ### Changes made **Workspace root (residual/.agent):** - ✅ Updated `AGENTS.md` — `res-init` → `residual-init`, `res-login` → `residual-login` - ✅ Rewrote `CLAUDE.md` to match current `AGENTS.md` - ✅ Deleted `.agent/notes/architecture.md` (pre-core layout) **core/ repo:** - ✅ Renamed `cmd/res-init/` → `cmd/residual-init/` - ✅ Renamed `cmd/res-login/` → `cmd/residual-login/` - ✅ Updated `core/.agent/claude/handoff.md`, `notes.md`, `todo.md` **docs/ repo:** - ✅ `docs/init-design.md` — fixed architecture diagram, dependency graph, package paths, binary names - ✅ `docs/os/os.md` — fixed binary names (`residual-sh` → `res-sh`, `residual-console` → `res-console`, persistence CLI `residual` → `res-os`) - ✅ `docs/architecture.md` — fixed package paths and binary names - ✅ `docs/design/tooling.md` — fixed build commands and binary names - ✅ `docs/design/aesthetic.md` — fixed `residual-console` reference - ✅ `docs/design/lua-scripting.md` — fixed `res-init` references - ✅ `docs/keymap.md` — fixed title - ✅ `docs/console/console.md` — fixed title - ✅ `docs/console/console-design.md` — fixed title - ✅ `docs/console/scripting.md` — fixed title - ✅ `docs/res-init-client.md` — fixed all `res-init` references - ✅ `docs/res-dispatcher.md` — fixed `res-login` reference - ✅ `docs/README.md` — fixed binary names - ✅ `.opencode/agents/*.md` — fixed binary names in agent harness files - ✅ `.opencode/skills/residual/SKILL.md` — fixed binary names and paths ### Verification - ✅ `cd core && go build ./...` — PASS - ✅ `cd core && CGO_ENABLED=1 go test ./...` — PASS - ✅ `cd extra && go build ./... && go test ./...` — PASS ### Commits pushed - `residual/.agent`: `d2d63dc` — docs: update AGENTS.md binary names, delete stale architecture.md - `residual/core`: `99ef311` — refactor: rename cmd/res-init → cmd/residual-init, cmd/res-login → cmd/residual-login - `residual/docs`: `5e15a56` — docs: fix stale binary names, package paths, and build commands

No labels

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

residual/.agent#12

No description provided.

Rows
Columns

Cleanup stale documents across all repos #12

Plan: Cleanup stale documents across all repos

Goal

Background

Documents to DELETE

1. CLAUDE.md (workspace root)

2. .agent/notes/architecture.md

Documents to REWRITE

3. docs/init-design.md — Major rewrite

4. docs/os/os.md — Major rewrite

5. docs/architecture.md — Minor rewrite

6. docs/design/tooling.md — Minor rewrite

7–10. Console docs — Title/header fixes

11. docs/design/aesthetic.md — Minor fix

12–14. core/.agent/claude/ files

Documents to REVIEW

15. os/README.md

Implementation steps

Risks

Verification checklist

Corrections from user review

1. CLAUDE.md should be REWRITTEN, not deleted

2. Binary naming: residual-login is correct, res-login is wrong

3. Updated action items

4. Note on residual-* vs res-* naming

Additional correction: residual-init naming

Files affected by res-init → residual-init

Complete naming convention (confirmed)

Updated action items for issue #12

Implementation complete ✅

Changes made

Verification

Commits pushed

1. `CLAUDE.md` (workspace root)

2. `.agent/notes/architecture.md`

3. `docs/init-design.md` — Major rewrite

4. `docs/os/os.md` — Major rewrite

5. `docs/architecture.md` — Minor rewrite

6. `docs/design/tooling.md` — Minor rewrite

11. `docs/design/aesthetic.md` — Minor fix

12–14. `core/.agent/claude/` files

15. `os/README.md`

2. Binary naming: `residual-login` is correct, `res-login` is wrong

4. Note on `residual-` vs `res-` naming

Additional correction: `residual-init` naming

Files affected by `res-init` → `residual-init`