Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .github/workflows/changelog-fragment-guard.yml
Original file line number Diff line number Diff line change
Expand Up @@ -140,7 +140,7 @@ jobs:
src/scripts/check-changelog-fragment.sh "$BASE_REF"


# api-reference.md `pkg/<file>:<line>` citations go stale when a PR edits
# api-reference.md and api-reference/*.md `pkg/<file>:<line>` citations go stale when a PR edits
# a route-registering server.go. The `relative links and anchors resolve`
# job reports that too, but it is not a required check, so the causing PR
# merged red and every later PR inherited the failure (#11866). This
Expand All @@ -157,7 +157,7 @@ jobs:
exit 0
fi
if ! bash src/scripts/check-api-reference-citations.sh; then
echo "::error::This PR edited a server.go or static pages and src/docs/api-reference.md citations drifted. Run 'bash src/scripts/check-api-reference-citations.sh --fix' and commit the result. If static pages under src/pkg/dashboard/ also changed, lower the matching baseline in src/pkg/dashboard/webstatic/style_ratchet_test.go (styleRatchetBaselines) in the same PR."
echo "::error::This PR edited a server.go or static pages and src/docs/api-reference.md / api-reference/*.md citations drifted. Run 'bash src/scripts/check-api-reference-citations.sh --fix' and commit the result. If static pages under src/pkg/dashboard/ also changed, lower the matching baseline in src/pkg/dashboard/webstatic/style_ratchet_test.go (styleRatchetBaselines) in the same PR."
exit 1
fi

Expand Down
5 changes: 3 additions & 2 deletions .github/workflows/docs-link-check.yml
Original file line number Diff line number Diff line change
Expand Up @@ -105,12 +105,13 @@ jobs:
- name: Check src/docs/ relative links and anchors
run: python3 src/scripts/check-docs-links.py src/docs

# Verifies every `pkg/<file>:<line>` citation in api-reference.md still
# Verifies every `pkg/<file>:<line>` citation in api-reference.md and
# api-reference/*.md still
# points at the route registration it names (hivecommons/hive#6628).
- name: Self-test the api-reference citation checker
run: bash src/scripts/test-check-api-reference-citations.sh

- name: Check api-reference.md source citations
- name: Check api-reference source citations
run: bash src/scripts/check-api-reference-citations.sh

# Verifies repo-local file:line citations across every src/docs/*.md file
Expand Down
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,4 +15,4 @@ These rules apply to every AI agent (hive agents, Copilot CLI, Claude Code, Code
- Keep changes surgical and PR-sized; one concern per PR.
- Every PR with a user-visible `src/` code change needs a `changelog.d/<category>-<slug>.md` fragment (`added|changed|deprecated|fixed|security`) whose body is a single `- ` bullet. Changes outside `src/` (root-level docs, `changelog.d/`, `.github/`), plus `src/docs/`, `*_test.go` files, and `src/{deploy,scripts}/test[-_]*.sh` scripts, are exempt automatically (`src/scripts/check-changelog-fragment.sh` is the source of truth for the exact set); other test-adjacent changes (e.g., `testdata/` fixtures, non-`_test.go` test helpers) and non-user-visible `src/` code changes (refactors, dependency bumps) need the `no-changelog` label instead. `changelog.d/` is at the repository root, not under `src/` — `src/changelog.d/` is never compiled and the guard rejects it.
- Sign commits (`git commit -s`); PR titles start with an emoji (`✨` feature, `🐛` fix, `📖` docs, `📝` proposal, `🌱` chore, `⚠️` breaking) — `📝` is for proposals only; a docs PR is `📖 docs: …`.
- Do not hand-edit `src/docs` file:line citations (including `src/docs/api-reference.md`); when CI's citation guard reports drift, run `python3 src/scripts/check-docs-citations.py --fix` first — it runs `check-api-reference-citations.sh --fix` for `api-reference.md` and re-anchors other `.go` citations by their backticked Go declaration anchor. Only fall back to a manual edit for citations it still reports as `DRIFT`/`UNRESOLVED`, and run it only when CI tells you citations drifted. The required `changelog-fragment-guard` check runs it (non-fix) when a PR edits a hub or dashboard `server.go` or their `static/` pages, so the PR that causes drift goes red.
- Do not hand-edit `src/docs` file:line citations (including `src/docs/api-reference.md` and `src/docs/api-reference/*.md`); when CI's citation guard reports drift, run `python3 src/scripts/check-docs-citations.py --fix` first — it runs `check-api-reference-citations.sh --fix` for `api-reference.md` and re-anchors other `.go` citations by their backticked Go declaration anchor. Only fall back to a manual edit for citations it still reports as `DRIFT`/`UNRESOLVED`, and run it only when CI tells you citations drifted. The required `changelog-fragment-guard` check runs it (non-fix) when a PR edits a hub or dashboard `server.go` or their `static/` pages, so the PR that causes drift goes red.
1 change: 1 addition & 0 deletions changelog.d/changed-api-reference-split.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- `src/docs/api-reference.md` is now an index over per-area pages in `src/docs/api-reference/<area>.md` (health/status, snapshots, auth, configuration, agents and controls, packs and ACMM, cost, knowledge, contribute, nous, inception, beads, dashboard misc, hub SaaS, hub server), so a route change touches one small page instead of one 760-line table and PRs stop conflicting on it ([#15299](https://github.com/hivecommons/hive/issues/15299)). `check-api-reference-citations.sh` walks the index and every area page by default (a file or directory may still be passed) and `--fix` rewrites only the page whose citations drifted; existing `api-reference.md#<section>` anchors still resolve.
2 changes: 1 addition & 1 deletion src/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -366,7 +366,7 @@ The `deploy/` directory contains pre-built configurations for common deployment
- [Operator reference](docs/operator-reference.md) — config blocks, server flags/env, GitHub token scopes.
- [Troubleshooting](docs/troubleshooting.md) — container logs, config validation, agent sessions, dashboard auth, and GitHub credential checks.
- [Config layering](docs/config-layering.md) — effective config provenance and precedence.
- [Dashboard API reference](docs/api-reference.md) — generated route index.
- [Dashboard API reference](docs/api-reference.md) — route index, one page per area under `docs/api-reference/`.
- [apiproxy](docs/apiproxy.md) — model API proxy purpose and deployment notes.
- [CNCF Code of Conduct](../CODE_OF_CONDUCT.md) — Hive adopts the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/main/code-of-conduct.md) for project participation.

Expand Down
2 changes: 1 addition & 1 deletion src/docs/acmm-advisor.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,7 @@ A recommendation (`Recommendation` struct, `src/pkg/acmmadvisor/acmmadvisor.go:1

## The API endpoint

`GET /api/acmm-recommendation` returns the JSON-encoded `Recommendation` computed from the hive's live signals. See the full request/response contract in the [API reference](api-reference.md#packs-and-acmm).
`GET /api/acmm-recommendation` returns the JSON-encoded `Recommendation` computed from the hive's live signals. See the full request/response contract in the [API reference](api-reference/packs-and-acmm.md).

## Open questions

Expand Down
2 changes: 1 addition & 1 deletion src/docs/agent-configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -127,7 +127,7 @@ older overlays, but new configs should use `bob.session_label`.
# launch_cmd, prompt, tools, and skills at launch.
```

The dashboard API can update this field through [`POST /api/effort/{agent}/{effort}`](api-reference.md#agents-and-controls).
The dashboard API can update this field through [`POST /api/effort/{agent}/{effort}`](api-reference/agents-and-controls.md).

The dashboard shows a reasoning-effort dropdown next to the model picker for every method that has an effort control (`codex`, `agy`, `claude`, and `omp`). The value is validated at set time against the method's own set, so a `codex`-only level such as `minimal` is refused for a `claude` agent rather than stored and dropped at launch. For `omp`, the dropdown is per selected model: Hive reads `omp models --json` and uses that model's `thinking` levels, hiding the control for models that report no thinking support. Picking `default` clears the stored value; for `claude` and `omp` that means no effort flag at all and the CLI's own default. The dropdown persists through the same path as the model picker (`hive.yaml` plus the per-agent overlay under `agents_dir`), which is the durable path on a hosted spoke: a hand edit of the agent's file is reverted by the next sync, the dashboard write is not. Each dropdown change is recorded in the audit trail as `set_reasoning_effort` with the new value, like the other per-agent setting changes. The effort the agent was actually launched with is what the run rows and the `- hive:` PR trailer report, so a `claude` agent at `xhigh` shows `effort=xhigh` there and an agent with no stored effort shows none.

Expand Down
Loading
Loading