From fe53984c4092ef00cab51b1ddd77c5b890786670 Mon Sep 17 00:00:00 2001 From: Ogulcan Celik Date: Tue, 19 May 2026 05:16:50 +0300 Subject: docs: stage website docs for next release --- .pi/prompts/pre-release-audit.md | 16 +- AGENTS.md | 6 +- CONTRIBUTING.md | 2 +- docs/next/website/src/content/docs/agent-skill.mdx | 103 +++++++++ docs/next/website/src/content/docs/agents.mdx | 129 +++++++++++ .../website/src/content/docs/cli-reference.mdx | 192 +++++++++++++++++ docs/next/website/src/content/docs/concepts.mdx | 85 ++++++++ .../website/src/content/docs/configuration.mdx | 238 +++++++++++++++++++++ docs/next/website/src/content/docs/index.mdx | 104 +++++++++ docs/next/website/src/content/docs/install.mdx | 58 +++++ .../next/website/src/content/docs/integrations.mdx | 130 +++++++++++ .../src/content/docs/persistence-remote.mdx | 125 +++++++++++ docs/next/website/src/content/docs/quick-start.mdx | 80 +++++++ docs/next/website/src/content/docs/socket-api.mdx | 224 +++++++++++++++++++ justfile | 22 +- 15 files changed, 1499 insertions(+), 15 deletions(-) create mode 100644 docs/next/website/src/content/docs/agent-skill.mdx create mode 100644 docs/next/website/src/content/docs/agents.mdx create mode 100644 docs/next/website/src/content/docs/cli-reference.mdx create mode 100644 docs/next/website/src/content/docs/concepts.mdx create mode 100644 docs/next/website/src/content/docs/configuration.mdx create mode 100644 docs/next/website/src/content/docs/index.mdx create mode 100644 docs/next/website/src/content/docs/install.mdx create mode 100644 docs/next/website/src/content/docs/integrations.mdx create mode 100644 docs/next/website/src/content/docs/persistence-remote.mdx create mode 100644 docs/next/website/src/content/docs/quick-start.mdx create mode 100644 docs/next/website/src/content/docs/socket-api.mdx diff --git a/.pi/prompts/pre-release-audit.md b/.pi/prompts/pre-release-audit.md index f3d9ce8f..11e42eb0 100644 --- a/.pi/prompts/pre-release-audit.md +++ b/.pi/prompts/pre-release-audit.md @@ -62,25 +62,25 @@ Process: 7. Audit next-release public docs. - Treat root `README.md` and `website/src/content/docs/` as the latest released public docs. - - Treat `docs/next/README.md` as the next-release root README. - - Compare meaningful user-facing changes in the range against root README and website docs. + - Treat `docs/next/README.md` as the next-release root README, and `docs/next/website/src/content/docs/` as the full next-release mirror of website docs. + - Compare meaningful user-facing changes in the range against next-release docs first. - Flag missing release docs for new or changed features, commands, config keys, protocol behavior, integrations, defaults, and compatibility notes. - - Compare `docs/next/README.md` against root `README.md`. Flag each difference as intended to ship in this release, stale, or needing user decision. - - Also audit website docs and example config snippets for release readiness. + - Compare `docs/next/README.md` against root `README.md`, and compare the staged website-doc mirror against `website/src/content/docs/`. Flag each difference as intended to ship in this release, stale, or needing user decision. + - Also audit example config snippets for release readiness. 8. Verify finalization state. - - Before `just release`, approved `docs/next/README.md` must be copied to root `README.md`, approved website doc changes must be present under `website/src/content/docs/`, and the deleted root doc files must stay deleted. + - Before `just release`, approved `docs/next/README.md` must be copied to root `README.md`, approved staged website docs must be copied from `docs/next/website/src/content/docs/` to `website/src/content/docs/`, and the deleted root doc files must stay deleted. - Run or recommend: ```bash just release-docs-check ``` - - This check must include root `README.md`, root `CHANGELOG.md`, the removed root doc files, and the required website docs. + - This check must include root `README.md`, root `CHANGELOG.md`, the removed root doc files, and exact 1:1 sync between `docs/next/website/src/content/docs/` and `website/src/content/docs/`. - Do not run `just release` unless the working tree is clean and the docs check passes. 9. Apply changes only when asked. - Do not edit files during the audit unless the user explicitly asks you to apply fixes. - - When asked to apply audit fixes, update `docs/next/CHANGELOG.md`, `docs/next/README.md`, and any required website docs. - - When asked to finalize release docs, copy approved next-release README and changelog into root, update the matching website docs, then run `just release-docs-check`. + - When asked to apply audit fixes, update `docs/next/CHANGELOG.md`, `docs/next/README.md`, and any required staged website docs under `docs/next/website/src/content/docs/`. + - When asked to finalize release docs, copy approved next-release README and changelog into root, copy approved staged website docs into `website/src/content/docs/`, then run `just release-docs-check`. Output format: diff --git a/AGENTS.md b/AGENTS.md index f87866a0..9da6753a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -52,9 +52,9 @@ Unit tests live next to the code (`#[cfg(test)] mod tests`). If you add behavior - Conventional commits, lowercase, no emojis. - Do not edit root `README.md` or `CHANGELOG.md` during normal feature or fix work unless explicitly asked. Maintainers prepare `docs/next/README.md` and `docs/next/CHANGELOG.md` during release review. -- Treat website docs under `website/src/content/docs/` as the latest released public docs. Do not document unreleased behavior there during normal feature or fix work. -- Treat `docs/next/README.md` and `docs/next/CHANGELOG.md` as next-release staging for the root README and changelog. -- Before release, copy approved next-release docs into their released locations: `docs/next/README.md` to `README.md`, `docs/next/CHANGELOG.md` to `CHANGELOG.md`, and approved website doc changes to `website/src/content/docs/`. `just release-docs-check` verifies README/changelog sync, the website docs are present, and the removed root docs stay removed. +- Treat website docs under `website/src/content/docs/` as the latest released public docs. These are Astro Starlight MDX docs published on herdr.dev. Do not document unreleased behavior there during normal feature or fix work. +- Treat `docs/next/README.md` and `docs/next/CHANGELOG.md` as next-release staging for the root README and changelog. Treat `docs/next/website/src/content/docs/` as a full next-release mirror of `website/src/content/docs/`; these staged MDX files are the source for the next herdr.dev docs. +- During normal work, update `docs/next/website/src/content/docs/` for unreleased website doc changes, not `website/src/content/docs/`. Before release, copy the approved mirror back to `website/src/content/docs/`. `just release-docs-check` verifies README/changelog sync, the website docs mirror is 1:1 with released website docs, and the removed root docs stay removed. - Put local PRDs, planning notes, and exploratory specs under `.prd/`; that directory is ignored and locally controlled. - When a normal feature or fix commit relates to a GitHub issue, add a commit body line `refs #` after the subject. Use this shape: ```text diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a79aa29b..604899d4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -52,7 +52,7 @@ If you plan to implement the change yourself, say that directly in the issue and The root `README.md`, root `CHANGELOG.md`, and website docs describe the latest released version of herdr. Do not update root `README.md`, root `CHANGELOG.md`, or `website/src/content/docs/` for normal PRs. -If your PR changes user-facing behavior, mention the needed public-doc update in the PR. Update `docs/next/README.md` only when the root README needs to change for the next release. +If your PR changes user-facing behavior, mention the needed public-doc update in the PR. Update `docs/next/README.md` only when the root README needs to change for the next release. Update the full website-doc mirror under `docs/next/website/src/content/docs/` when website docs need to change for the next release. You do not need to edit the changelog for normal PRs. Maintainers prepare `docs/next/CHANGELOG.md` during release review. diff --git a/docs/next/website/src/content/docs/agent-skill.mdx b/docs/next/website/src/content/docs/agent-skill.mdx new file mode 100644 index 00000000..65327c33 --- /dev/null +++ b/docs/next/website/src/content/docs/agent-skill.mdx @@ -0,0 +1,103 @@ +--- +title: Agent skill +description: A concise guide for coding agents running inside Herdr. +--- + +This page teaches coding agents how to use Herdr while they are running inside a Herdr pane. + +Use Herdr to organize parallel work instead of stacking everything in one terminal. + +## Core model + +Herdr has four levels: + +| Level | Meaning | +| --- | --- | +| Workspace | A project or task context. | +| Tab | A view inside a workspace. | +| Pane | A terminal area inside a tab. | +| Agent | A detected coding agent running in a pane. | + +Use workspace and tab actions for layout. Use pane actions for commands and output. + +## Read the current layout + +```bash +herdr pane list +``` + +Use the pane IDs returned by Herdr for later commands. + +## Create a helper pane + +Split a pane and run a command: + +```bash +herdr pane split 1-1 --direction right +herdr pane run 1-2 "just test" +``` + +Prefer `pane run` over sending raw keys when you want to submit a full command line. + +## Read output + +```bash +herdr pane read 1-2 --source recent --lines 80 +``` + +Use `recent-unwrapped` when reading logs or matching long lines. + +```bash +herdr pane read 1-2 --source recent-unwrapped --lines 120 +``` + +## Wait for agents + +Wait for another agent to finish or become blocked: + +```bash +herdr wait agent-status 1-3 --status done +herdr wait agent-status 1-3 --status blocked +``` + +Use agent waits for recognized coding agents. Use normal output matching for ordinary commands, servers, and tests. + +## Preserve focus + +Do not steal visible focus unless the user asked for it. Create panes, submit commands, and read output without changing the user’s active view when possible. + +## Use clear pane aliases + +When your tool supports aliases, use names like `server`, `tests`, `reviewer`, or `docs`. This makes later pane operations easier to audit. + +## Good patterns + +Run long work in a separate pane: + +```bash +herdr pane split 1-1 --direction right +herdr pane run 1-2 "just check" +``` + +Watch a server until it is ready: + +```bash +herdr pane read 1-2 --source recent-unwrapped --lines 80 +``` + +Ask a reviewer agent to inspect a change: + +```bash +herdr pane split 1-1 --direction right +herdr pane run 1-2 "pi --model " +``` + +## Avoid these patterns + +Do not pile every command into the current pane. + +Do not use raw key injection for command submission when `pane run` is available. + +Do not wait for `agent-status` on a normal process that is not a coding agent. + +Do not change implementation direction without telling the user. diff --git a/docs/next/website/src/content/docs/agents.mdx b/docs/next/website/src/content/docs/agents.mdx new file mode 100644 index 00000000..e3d2bc0c --- /dev/null +++ b/docs/next/website/src/content/docs/agents.mdx @@ -0,0 +1,129 @@ +--- +title: Agents +description: See what Herdr can detect, how agent state works, and how integrations improve it. +--- + +Herdr is useful because it knows when agents are working, blocked, done, or idle. You can scan the sidebar instead of checking every pane manually. + +## Supported agents + +Automatic detection works out of the box for common coding agents. + +| Agent | Idle / done | Working | Blocked | +| --- | --- | --- | --- | +| Pi | yes | yes | partial | +| Claude Code | yes | yes | yes | +| Codex | yes | yes | yes | +| Droid | yes | yes | yes | +| Amp | yes | yes | yes | +| OpenCode | yes | yes | yes | +| Grok CLI | yes | yes | yes | +| Hermes Agent | yes | yes | yes | +| GitHub Copilot CLI | yes | yes | yes | + +Detected but less thoroughly tested: Gemini CLI, Cursor Agent, Cline, and Kimi. + +Unsupported agents still run normally as terminal processes. They just may not get rich state unless you add an integration or report state over the socket API. + +## How detection works + +Herdr combines three signals: + +1. foreground process detection +2. terminal output heuristics +3. integration state reports + +Process detection tells Herdr which pane owns an agent. Heuristics infer state when no hook is available. Integrations provide the most precise semantic state. + +## State rollups + +The sidebar rolls state upward. + +A blocked agent makes its pane, tab, and workspace look blocked. A working agent makes the workspace look active. A done agent stays visible until you view it. + +This lets you scan many projects quickly. + +## Direct integrations + +Install integrations for agents that expose hooks or plugins: + +```bash +herdr integration install pi +herdr integration install claude +herdr integration install codex +herdr integration install opencode +herdr integration install hermes +``` + +Check installed integration versions: + +```bash +herdr integration status +``` + +Show only outdated integrations: + +```bash +herdr integration status --outdated-only +``` + +## Custom agent labels + +You can rename an agent target for display: + +```bash +herdr agent rename 1-1 reviewer +herdr agent rename reviewer --clear +``` + +Targets accept terminal IDs, unique agent names, detected or reported agent labels, and legacy pane IDs. + +## Custom status labels + +Integrations can report a visual status label without changing semantic state. + +```bash +herdr pane report-agent 1-1 \ + --source custom:indexer \ + --agent docs-bot \ + --state working \ + --custom-status indexing +``` + +`state` controls waits, notifications, and rollups. `custom-status` is only display text. + +## Start agents from the CLI + +Use `herdr agent ...` commands when you want a terminal to be treated as an agent target. Agent targets show up in `agent list`, can be read or sent input by agent name, can be waited on by agent state, and can be directly attached. + +Spawn an agent into Herdr from a script: + +```bash +herdr agent start reviewer --cwd ~/project --split right -- pi +``` + +You can place that agent in a specific workspace or tab: + +```bash +herdr agent start docs --workspace 1 --tab 1-1 -- claude +``` + +Use `herdr pane ...` commands for ordinary terminals, servers, tests, shells, and low-level terminal input. For example, use `pane split` and `pane run` for `cargo test`, not `agent start`, unless that terminal is intentionally being treated as an agent target. + +## Attach directly to an agent + +Attach your current terminal to one agent terminal instead of the full Herdr UI: + +```bash +herdr agent attach reviewer +``` + +Detach with `ctrl+b q`. Send a literal `ctrl+b` with `ctrl+b ctrl+b`. + +Use `--takeover` if another direct attach client already owns input: + +```bash +herdr agent attach reviewer --takeover +``` + +Use `herdr terminal attach ` when you want the same direct attach behavior for a non-agent terminal. diff --git a/docs/next/website/src/content/docs/cli-reference.mdx b/docs/next/website/src/content/docs/cli-reference.mdx new file mode 100644 index 00000000..57f495c1 --- /dev/null +++ b/docs/next/website/src/content/docs/cli-reference.mdx @@ -0,0 +1,192 @@ +--- +title: CLI reference +description: Herdr commands for sessions, workspaces, tabs, panes, agents, waits, integrations, and status. +--- + +Herdr’s CLI talks to the running server over the same local socket API used by integrations and agents. + +Most commands print JSON responses. Use them from scripts when you want deterministic automation. + +## Launch and status + +```bash +herdr # launch or attach to the default session +herdr --session work # launch or attach to a named session +herdr --remote workbox # attach through SSH +herdr --no-session # single-process escape hatch +herdr --default-config # print default config +herdr --version # print version +``` + +Status commands: + +```bash +herdr status +herdr status server +herdr status client +``` + +## Server + +```bash +herdr server stop +herdr server reload-config +``` + +`reload-config` applies reloadable settings without restarting panes. + +## Sessions + +```bash +herdr session list [--json] +herdr session attach +herdr session stop [--json] +herdr session delete [--json] +``` + +Use `default` as the session name when you need to stop the default session explicitly. + +## Workspaces + +```bash +herdr workspace list +herdr workspace create [--cwd PATH] [--label TEXT] [--focus] [--no-focus] +herdr workspace get +herdr workspace focus +herdr workspace rename