Conversation
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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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)
make docker-multiarch-push ARGS="--latest --version vX.Y.Z"as the explicit non-interactive form, and--no-latestfor backport tags that must not move:latest.docker-interactive-multiarch*), note that both paths converge on the samebuild_docker_image()call, and record the two real differences:--tagvs--version, and thatlrops.py dockervalidates the tag exists whilebuild --dockerdoes not.The wiki's
docker --context gitlabsteps 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:
settings/instance.md,settings/storage.mdcanManageInstanceConfig— super_admin or a self-hosted org ownersettings/deployment.md,settings/smtp.mdcanManageCurrentOrg— owner or super_adminsettings/license.md!isCloudMode())reports/*Content fixes:
reports/onboarding-report.mddescribed 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.mdomittedDashboardGridentirely — 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,/summaryfields, 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.subscribe.md,licenses/license-management.md, andsettings/plan-and-usage.mdstill described the seat flow as the current way to make room for a teammate. Reframed; seat UI is marked legacy.hexmos_docs/corpus, so none 404. The convention is recorded inREADME.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:
App.tsxand the nested routers.ui/src/...component paths in docs confirmed to exist.hexmos_docs/.Security scans, all clean:
make security-gitleaks— no leaks (2321 commits)make security-osv— cleanmake security-govulncheck— 0 vulnerabilities calledmake security-semgrep— 2 WARNING findings, both reviewed and false positives (agojqJSON round-trip flagged as CWE-502, which doesn't apply to Go'sencoding/json; and a dev-only script'surllibcall whose URLs are all hardcoded literals)Follow-ups not in this PR
livi.answering.licensing) so Livi never invents a purchase flow, rather than depending on the right chunk being retrieved.Settings.tsx— the drift behind all six wrong access claims would then fail CI instead of reaching users./reports. Documented as such, but it may warrant a menu entry.