Skip to content

docs: backfill missing project documentation#181

Open
iamlasse wants to merge 1 commit into
marcus:mainfrom
iamlasse:docs/backfill-missing-docs
Open

docs: backfill missing project documentation#181
iamlasse wants to merge 1 commit into
marcus:mainfrom
iamlasse:docs/backfill-missing-docs

Conversation

@iamlasse

Copy link
Copy Markdown

Summary

Backfills the standard project-level documentation that was missing from the repo. The Go code itself is already fully documented (all exported decls have doc comments; only 1 of 24 packages lacked a // Package doc), so this PR targets the project artifacts rather than code comments.

Changes

  • CONTRIBUTING.md (new) — prerequisites, the dev loop via make targets (build, test, test-race, coverage, lint), the pre-commit hook (make install-hooks → gofmt/go vet/go build, bypass via --no-verify), branch + PR workflow, and the required commit-trailer convention (Nightshift-Task / Nightshift-Ref). Grounded in the existing Makefile, scripts/pre-commit.sh, and the README Development section.
  • ARCHITECTURE.md (new) — module overview, the cmd/ layer, and the internal/ packages grouped by responsibility (config/state/db, agents/providers/integrations, tasks/scheduler/orchestrator, budget/calibration feedback loop, security, observability, analysis, projects/setup). Package descriptions are taken from each package's own doc comment; dependency edges are verified from imports. References docs/guides/run-lifecycle.md for the runtime flow rather than duplicating it. Inferred relationships are explicitly flagged as assumptions.
  • cmd/provider-calibration/main.go — added the missing // Command provider-calibration package doc (the only package of 24 lacking one), describing it as the standalone diagnostic tool that aggregates Codex/Claude session metrics to suggest a budget-calibration multiplier.
  • website/docs/cli-reference.md — audited against the actual cobra command tree and backfilled genuine gaps: added the missing top-level commands (config, init, report, install, uninstall, busfactor) to the command table, and added new Configuration Commands and Daemon Commands sections documenting the config get/set/validate and daemon start/stop/status subcommands and their flags.

Verification

  • gofmt -l . → empty
  • go vet ./... → clean
  • go build ./... → clean
  • go test ./... → all pass
  • go doc ./cmd/provider-calibration → new package doc renders

Notes

  • No internal/sandbox or internal/ui package exists; references to a sandbox layer were treated as non-existent (not fabricated).
  • Markdown docs are intentionally grounded in existing tooling and source to keep hallucination risk low; inferred architectural relationships in ARCHITECTURE.md are marked as assumptions.

Nightshift-Task: docs-backfill
Nightshift-Ref: https://github.com/marcus/nightshift

Add CONTRIBUTING.md (dev loop, Makefile targets, pre-commit hook, branch/PR workflow, commit trailer convention) and ARCHITECTURE.md (module overview, cmd layer, internal packages grouped by responsibility, with inferred relationships flagged as assumptions). Add the missing package doc comment to cmd/provider-calibration, and backfill website/docs/cli-reference.md with the missing config/init/report/install/uninstall/busfactor commands plus daemon and config subcommand details.

Nightshift-Task: docs-backfill
Nightshift-Ref: https://github.com/marcus/nightshift
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant