Skip to content

Docs: make AGENTS.md the release source of truth, and fix the chatbot's route docs - #116

Merged
lovestaco merged 6 commits into
masterfrom
fix/lrops
Sep 10, 2026
Merged

Docs: make AGENTS.md the release source of truth, and fix the chatbot's route docs#116
lovestaco merged 6 commits into
masterfrom
fix/lrops

Conversation

@lovestaco

@lovestaco lovestaco commented Sep 10, 2026

Copy link
Copy Markdown
Contributor

Summary

Two related pieces of documentation work, plus one small UI fix.

1. AGENTS.md is now the single source of truth for the release process. The internal flyweight wiki page "LiveReview: Publishing Updates for the Self-Hosted Version" can be deleted once this merges — everything still accurate from it has been folded in here.

2. The chatbot's route documentation (internal/docindex/docs/routes_guide/) was audited against the actual code, after Livi gave a user a wrong answer about onboarding a team member. Several factual errors turned out to be feeding it.

Release process (AGENTS.md)

  • Document make docker-multiarch-push ARGS="--latest --version vX.Y.Z" as the explicit non-interactive form, and --no-latest for backport tags that must not move :latest.
  • Document the interactive targets (docker-interactive-multiarch*), note that both paths converge on the same build_docker_image() call, and record the two real differences: --tag vs --version, and that lrops.py docker validates the tag exists while build --docker does not.
  • Require agents to ask which mode to use rather than choosing.
  • Add a gotcha about disk space during multi-arch builds.

The wiki's docker --context gitlab steps were not carried over — that context was removed in 2825a9b.

Route docs audit

Checked every file on four axes. Route paths, component paths, and internal links were all correct; access/permission claims were wrong in six places, all the same way — docs said "super_admin only" for things org owners can also do:

File Was Actually
settings/instance.md, settings/storage.md super_admin only canManageInstanceConfig — super_admin or a self-hosted org owner
settings/deployment.md, settings/smtp.md super_admin only canManageCurrentOrg — owner or super_admin
settings/license.md "super_admin (cloud)" Tab is absent in cloud (!isCloudMode())
reports/* mixed APIs are any-org-member; only the mega menu is owner/admin-gated

Content fixes:

  • reports/onboarding-report.md described the wrong page. It claimed to track "who has/hasn't onboarded (installed CLI, connected AI provider, run a first review)". It doesn't — it's a 57-chart org analytics report (adoption, repos, engineers, quality, cost, engagement) with an async PDF/HTML export. The per-person checklist actually lives on the Dashboard. That name collision is what produced the bad answer.
  • dashboard.md omitted DashboardGrid entirely — the entire 13-widget chart grid was undocumented. Now covers the period selector, per-user layout persistence, and how to read each chart plus where it drills through.
  • reports/taxonomy-reports.md: the three modes, the URL-parameter filters that make mega-menu deep links work, /summary fields, and the CSV/XLSX dataset exports.
  • settings/integrations.md: replaced a four-line stub with the real Slack / Teams / Discord setup steps as the UI presents them.
  • Per-seat licensing is deprecated, but subscribe.md, licenses/license-management.md, and settings/plan-and-usage.md still described the seat flow as the current way to make room for a teammate. Reframed; seat UI is marked legacy.
  • Added a Learn more (public docs) section to 15 files. Every URL was verified against the synced hexmos_docs/ corpus, so none 404. The convention is recorded in README.md.

UI change

IntegrationsTab.tsx: removed the "Download the Livi icon" step from the Teams flow (Teams branding comes from the uploaded app package) and renumbered the remaining steps — they previously rendered 1, 2, 3, 4, 6, 7, 8, skipping 5. Azure Portal link normalized to a trailing slash.

Testing

No UI build was run (per repo convention). Verified by static checks:

  • All route paths cross-checked against App.tsx and the nested routers.
  • All ui/src/... component paths in docs confirmed to exist.
  • All internal markdown links resolve.
  • All public-docs URLs map to a real page in hexmos_docs/.

Security scans, all clean:

  • make security-gitleaks — no leaks (2321 commits)
  • make security-osv — clean
  • make security-govulncheck — 0 vulnerabilities called
  • make security-semgrep — 2 WARNING findings, both reviewed and false positives (a gojq JSON round-trip flagged as CWE-502, which doesn't apply to Go's encoding/json; and a dev-only script's urllib call whose URLs are all hardcoded literals)

Follow-ups not in this PR

  • A LawBook rule (e.g. livi.answering.licensing) so Livi never invents a purchase flow, rather than depending on the right chunk being retrieved.
  • A task-oriented "onboard a team member" doc, so the sequence isn't reassembled from four route pages each time.
  • A test asserting the Settings tab-id → gating table matches Settings.tsx — the drift behind all six wrong access claims would then fail CI instead of reaching users.
  • The Onboarding Report has no mega-menu entry, reachable only via a link on /reports. Documented as such, but it may warrant a menu entry.

lovestaco and others added 6 commits September 10, 2026 19:26
Fold the still-relevant parts of the internal flyweight wiki page
"LiveReview: Publishing Updates for the Self-Hosted Version" into
AGENTS.md so the repo is the single source of truth for the release
process. The wiki page's docker context steps were already obsolete
(dropped in 2825a9b) and are not carried over.

- Document the explicit non-interactive form,
  make docker-multiarch-push ARGS="--latest --version vX.Y.Z", plus
  --no-latest for backport tags that must not move :latest.
- Document the interactive targets (docker-interactive-multiarch*),
  note that both paths converge on the same build_docker_image() call,
  and record the two real differences: --tag vs --version, and that
  lrops.py docker validates the tag exists while build --docker does not.
- Require agents to ask the user which mode to use rather than choosing.
- Add a gotcha about disk space on the build machine during multi-arch
  builds.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013xQQCYSxKhLKSMiMeBwndL
Audited every file in internal/docindex/docs/routes_guide against the
actual code. Fixes several factual errors that were feeding Livi wrong
answers, and fills in the parts of the UI the corpus never described.

Access/permission corrections (same class of bug throughout: docs claimed
super_admin-only for things org owners can also do):
- settings/instance.md, settings/storage.md: gated by canManageInstanceConfig
  = super_admin or a self-hosted org owner, not super_admin alone.
- settings/deployment.md, settings/smtp.md: gated by canManageCurrentOrg
  = owner or super_admin.
- settings/settings-overview.md: same corrections in the summary table.
- reports/*: the /api/v1/reports/* groups are RequireAuth + org context, i.e.
  any org member; only the Reports mega-menu section is owner/admin-gated.
  Both facts are now stated separately.

Content corrections and expansion:
- reports/onboarding-report.md: the stated purpose was wrong. It is not a
  per-member setup checklist; it is a 57-chart org analytics report over
  seven sections, built from internal/onboardingreport/templates.json, with
  an async PDF/HTML export job. The per-person checklist actually lives on
  the Dashboard, which is what made this page easy to misdescribe.
- reports/taxonomy-reports.md: document the three modes, the URL-parameter
  filter set that makes mega-menu deep links work, the /summary fields, and
  the CSV/XLSX dataset exports alongside the PDF impact report.
- dashboard.md: the doc omitted DashboardGrid entirely. Document the period
  selector, per-user layout persistence, and all 13 widgets with how to read
  each chart and where it drills through.
- settings/integrations.md: replace the stub with the real Slack, Microsoft
  Teams, and Discord setup steps as the UI presents them.

Also drop the Livi icon download step from the Teams setup flow in
IntegrationsTab.tsx, and renumber the remaining steps - they previously
rendered 1,2,3,4,6,7,8, skipping 5.

Deleted route docs for pages being retired (per-seat licensing is
deprecated) and several auth/chatbot pages.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013xQQCYSxKhLKSMiMeBwndL
Two follow-ups to the routes_guide audit.

Per-seat licensing is deprecated, but three pages still described the seat
flow as the current way to make room for a team member:

- subscribe.md: upgrading is about plan tier and features, not headcount.
  Also note self-hosted instances never use this page - they unlock with a
  license key instead.
- licenses/license-management.md: marked a legacy page. Seat quantity is
  historical detail on older subscriptions; the page's live use (view plan,
  cancel) is documented as such.
- settings/plan-and-usage.md: document the Overview / Breakdown / Control
  sub-tabs and their deep links, and scope the assignment UI to legacy seat
  plans.

This also clears the last dangling links left by the deleted route docs.

Then, where a page is also covered by the public documentation site, add a
"Learn more (public docs)" section linking to it (15 files). URLs follow the
hexmos.com/livereview/docs base, mirroring the layout of the hexmos_docs
corpus, and every URL was checked against that synced copy so none of them
404. README.md records the convention, including the rule that only pages
actually present in hexmos_docs may be linked.

Note git-lrc/configure/integrations covers AI connector management (BYOK)
despite its name, so it is linked from ai/ai-providers.md rather than
git/git-providers.md, which has no public counterpart.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013xQQCYSxKhLKSMiMeBwndL
@lovestaco
lovestaco merged commit 5b9cabf into master Sep 10, 2026
15 checks passed
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