Skip to content

Split: packaging, docs and skills for the service (PR-1.13) - #607

Draft
ghackett wants to merge 3 commits into
split/1.12d-background-agentsfrom
split/1.13-packaging-docs
Draft

Split: packaging, docs and skills for the service (PR-1.13)#607
ghackett wants to merge 3 commits into
split/1.12d-background-agentsfrom
split/1.13-packaging-docs

Conversation

@ghackett

@ghackett ghackett commented Oct 5, 2026

Copy link
Copy Markdown
Member

PR-1.13 of the split-service spec: documentation and packaging only, no behaviour change. Based on PR 606's branch.

Packaging. The deb (build_deb.sh and debian/rules), rpm, PPA and AUR recipes all already installed collins-service.service to the user-unit directory and the collins-service command; verified, and dpkg -c of a local build_deb.sh build shows both. Fixed: build_deb.sh's control file lacked gir1.2-soup-3.0 (and the markdown libraries and recommends that debian/control carries), so the release .deb would not have run. CI now checks the deb's extracted tree and the rpm's installed files for the service command and the unit.

Docs. docs/guide/service.md completed (what runs where, starting, quit/detach/reopen, restart, the mismatch dialog, files and the proof rule, --check, logging); features, how-it-works, getting-started (upgrades need Restart service), FAQ and README updated. There is no Start at login setting, so the page says the unit is not enabled and shows systemctl --user enable.

AGENTS.md architecture page rewritten for two processes (the "in progress" paragraph is gone), state table, env overrides and how a check starts its service, and the feature map's Service row. Skills rewritten for the two-process design: terminal-tab, sessions-and-sidebar, session-mcp-tools, sandboxed-sessions, testing.

Changelogs. docs/releases.md v0.1.5 reads as one story; debian/changelog (still UNRELEASED) and the spec's %changelog carry matching condensed notes. The metainfo <release> is left alone: by release-branch-skill and verify_versions.py it is added at the cut and may not run ahead.

Verified: unit suite, ruff, verify_versions.py, npx vitepress build, run_e2e.py --list.

🤖 Generated with Claude Code

https://claude.ai/code/session_01KaKWL1rt93N7oKShnaQbqQ

@ghackett

ghackett commented Oct 5, 2026

Copy link
Copy Markdown
Member Author

@claude review

@claude

claude Bot commented Oct 5, 2026 •
edited
Loading

Copy link
Copy Markdown

Claude finished @ghackett's task in 4m 47s —— View job

Review complete

  • Read CLAUDE.md and repo instructions
  • Gather context: diff vs origin/split/1.12d-background-agents
  • Review packaging changes (build_deb.sh, debian/, packaging/fedora, ci.yml)
  • Review docs changes (docs/guide/service.md, features.md, how-it-works.md, getting-started.md, faq.md, README)
  • Review changelogs (debian/changelog, docs/releases.md, spec %changelog)
  • Review skills/AGENTS.md rewrite for accuracy vs current code

This is a docs/packaging-only PR as described, and it checks out well. I cross-referenced a large number of the rewritten claims against the actual code (not just prose consistency) and they all held up:

  • docs/guide/service.md's --check sample output, the backoff sequence (1, 2, 5, 10, 30), resume_on_start, the login-shell capture ($SHELL -lic 'env -0', 5s, fail-soft), --print-socket, and the protocol-mismatch behavior all match collins/connection.py and collins/service/main.py exactly.
  • AGENTS.md's architecture rewrite — ALREADY_RUNNING_MSGID/args.pty, service.restart, quit_with_running_sessions default, TOOL_BOUND_S = 14.0, ServiceCore — all verified against the code they describe.
  • The ci.yml additions (checking collins-service + the systemd unit are present in both the extracted .deb and the installed RPM tree) line up with the scripts/build_deb.sh and packaging/fedora/collins.spec changes they're meant to guard.
  • scripts/build_deb.sh's new Depends/Recommends match debian/control's, confirming the stated fix (missing gir1.2-soup-3.0, the markdown libs, the sandbox Recommends).
  • Skill files referencing new test modules (tests/liveservice.py, test_api_server.py, test_connection.py, test_client_boundary.py, scripts/check_service_survives_client.py, scripts/check_detach_reopen.py) — all exist and match the description.
  • Changelog entries (debian/changelog, the spec's %changelog) are condensed and consistent with each other and with docs/releases.md; the metainfo <release> is correctly left untouched per release-branch-skill.

Two minor, non-blocking things worth a look:

  1. scripts/build_deb.sh still carries one extra package in Recommends that debian/control doesn't have: gir1.2-glib-2.0 (pre-existing, not added by this PR, but the PR description frames this change as bringing build_deb.sh in line with debian/control's dependency list, and this one item is still out of sync between the two).
  2. Same file: the inserted comment sentence runs onto the end of the pre-existing libspelling comment line (...a missing typelib is a window that cannot start its service. libspelling is only recommended: composer.py degrades to an unchecked text all on one line) — purely cosmetic, doesn't affect the build.
  3. docs/guide/faq.md was edited (the "Does anything leave my machine?" answer, to mention collins-service) but doesn't carry the GPL modification-notice header that its sibling pages under docs/guide/ all have (and had bumped to 2026-10-05 in this same PR). I couldn't confirm with certainty whether faq.md predates the fork point a3a5a77 in this shallow checkout, but if it does, per the gpl-modified-file-notices skill this edit needs the notice added. Worth a git cat-file -e a3a5a77:docs/guide/faq.md check before merging.

No code/behavior changes in this PR, nothing else stood out.

ghackett and others added 2 commits October 5, 2026 09:19
@ghackett @claude
Packaging, docs and skills for the service (PR-1.13)
4273018 
The .deb's control file lists libsoup 3 and the other hard
dependencies, and CI checks that the deb and the rpm install the
service's command and user unit. The service guide is complete, the
features and how-it-works pages describe the two processes, AGENTS.md's
architecture page is rewritten for them, five skills are rewritten, and
the v0.1.5 changelogs read as one story.

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01KaKWL1rt93N7oKShnaQbqQ
@ghackett @claude
Address the review: wrap the build_deb.sh comment
fb90c41 
Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01KaKWL1rt93N7oKShnaQbqQ
@ghackett

ghackett commented Oct 5, 2026

Copy link
Copy Markdown
Member Author

🤖 Thanks. (1) Left gir1.2-glib-2.0 in build_deb.sh's Recommends: it is pre-existing and harmless, and removing it is outside this PR. (2) Fixed: the comment is wrapped again. (3) docs/guide/faq.md is not in the fork point (git cat-file -e a3a5a77:docs/guide/faq.md fails), so it carries no notice by design.

@ghackett
ghackett force-pushed the split/1.13-packaging-docs branch from bbac53b to fb90c41 Compare October 5, 2026 13:20
@ghackett @claude
Address the Fable review of PR 607
f4bd58d 
AGENTS.md and the service guide say the login-shell capture overlays
the service's environment (with the protected names), and that the
service, not the client's VTE, reads the CLI's progress reports. The
docstrings and four skills that still described Phase 1 or the loopback
describe the present design, and debian/control and build_deb.sh list
the same dependencies, gir1.2-glib-2.0 included.

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01KaKWL1rt93N7oKShnaQbqQ
@ghackett

ghackett commented Oct 5, 2026

Copy link
Copy Markdown
Member Author

🤖 Addressed the Fable review at f4bd58d: (1) AGENTS.md and the service guide now say the login-shell capture is overlaid on the service's environment, with COLLINS_, XDG_, PYTHONPATH, HOME, USER and the systemd variables protected and the service's leading PATH entries kept first. (2) Nothing in the client reads the progress termprop, so AGENTS.md says the service reads OSC 9;4 off the stream filter and the client's VTE only draws. (3) Docstring-only fixes for the Phase 1 and loopback prose across collins/ (no pre-fork file needed a date bump; app.py and terminal.py were already dated today). (4) The notifications, pull-requests, preferences and panel-dock skills lost their Phase 1 and loopback sentences. (5) debian/control now lists gir1.2-glib-2.0 in Depends and build_deb.sh matches. CI is green with e2e passed.

@ghackett
ghackett added this pull request to stack #616 October 6, 2026 18:41
@ghackett
ghackett removed this pull request from stack #616 October 6, 2026 18:44
@ghackett
ghackett added this pull request to stack #617 October 6, 2026 18:44

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@ghackett