* feat(cli): list and read agents by their Orca session ID with orca agent list/show/read Live terminal and chat agents are listed, shown and read by Orca session ID on the selected host; sleeping native agents can be shown and read by ID. Chat reads walk the chat's own bounded history pages back to the latest /clear. * fix(cli): agent show names a live agent and its last reply as agent list does; help says sleeping terminal agents aren't listed yet * Bound agent reads and scoped workspace inventories * fix(cli): agent read carries the conversation's state, so a running chat turn reads as working agent read now reports the same state agent list/show report, from the same status rows, in text (a leading state line) and --json (state). A turn still running no longer reads like a finished chat with no reply. * Fix agent conversation read consistency and limits * fix(cli): agent read derives its state from the history it returns agent read no longer samples live status. A chat's state comes from the journal snapshot that produced its entries: an open turn or an accepted send with no turn yet reads working; done needs an explicitly successful latest turn whose reply is the newest entry shown. A terminal agent's state comes from the provider turn markers in the same transcript bytes: a prompt with no end after it reads working, done needs an explicit end (Claude stop_reason, Codex task_complete) with the reply as the newest entry. Anything else omits state. The journal lane wait added for the live state is removed. * Tighten agent read snapshot evidence * Keep agent read done for finished turns A dead owner now only voids working. Codex completion is proved by the turn's own decoded reply rather than row adjacency, and Claude's by its end row's own reply, without needing the prompt inside the read window. * Adapt agent commands to reorganized shared contracts * Warn on incomplete agent lists, read sleeping transcript paths, and retry unanswered provider id lookups * Follow main's moved shared modules * Bound live transcript recovery to conversation panes * Show sleeping terminal agents where agent list lists them agent list lists a finished terminal agent while its pane sleeps, since main keeps that status row. agent show now counts the same sleeping place, and the help says which sleeping agents are listed. Messaging still ignores sleeping panes. * Clarify sleeping agent discovery and messaging help * Say sleeping terminal agents can't be messaged and note the WSL read exception * Follow the moved CLI argument boundary after rebasing * Show plain Orca session IDs in agent command help * Expect plain UUID Orca session IDs in the transcript source test * Follow main's moved shared modules after rebasing * Name Orca session IDs <id> in agent help, since older IDs keep their agent prefix * Follow main's moved agent-session modules after rebasing
@orca/docs
This package contains the product documentation and public media intended to ship alongside Orca's source code.
Open-source product documentation for Orca, served at /docs (same URL shape as https://orca.dev/docs).
This package is a self-contained Next.js app. It is intentionally not a root monorepo workspace member, so installing Electron app dependencies does not pull Next/fumadocs.
Local development
Use Node.js 24 and the pnpm version pinned in package.json. CI reads the
Node.js version from this package's engines.node field.
cd docs/site
pnpm install
pnpm dev
Open http://localhost:3004/docs.
Linting
Run pnpm lint inside this directory. The isolated Oxlint
configuration keeps the native equivalents of the previous Next.js, React,
React hooks and accessibility checks at their existing severities, including
alt text on Next.js Image components. Generated Next.js and MDX output is
excluded. Oxlint also reports its default correctness warnings.
The migration does not provide equivalents for React's deprecated-API check,
React Compiler configuration/gating diagnostics, or Next.js's relative
location.assign advisory. JSX variable-use bookkeeping is handled by Oxlint's
parser. Keep TypeScript and the production Next.js build in the validation
workflow; this is not a claim of complete ESLint rule parity.
Production build
cd docs/site
pnpm install
pnpm build
pnpm start
pnpm start serves the production build on port 3004. Paths:
| Path | Purpose |
|---|---|
/ |
Redirects to /docs |
/docs |
Docs index |
/docs/... |
Nested doc pages from content/docs |
/docs/api/search |
Fumadocs search index |
/docs/og/... |
Per-page Open Graph image route |
Layout
content/docs/— MDX pages +meta.jsonnavigationpublic/docs/— docs-only media, logo, and favicon (GIFs, posters, screenshots)src/app/docs/— fumadocs routes, OG imagessrc/components/— docs-scoped chrome (header/footer/search), not marketing site
Updating content
Treat the documentation tree as a deliberate publication boundary. Before importing source material, review the diff for internal references, credentials, third-party media rights, and feature/version claims, then copy only approved pages and assets. Keep the app shell and deployment configuration in this repository so a docs-only pull request can be reviewed and built independently.
Same-domain routing
The docs app is a separate Vercel project (the docs zone) and keeps the
public /docs URL namespace. The marketing site remains the default zone for
orca.dev; configure its Next/Vercel proxy with these beforeFiles
rewrites, replacing DOCS_ORIGIN with the docs project's production URL:
return {
beforeFiles: [
{
source: '/docs',
destination: `${DOCS_ORIGIN}/docs`
},
{
source: '/docs/:path*',
destination: `${DOCS_ORIGIN}/docs/:path*`
},
{
source: '/docs-static/:path*',
destination: `${DOCS_ORIGIN}/docs-static/:path*`
}
]
}
/docs-static is the docs zone's assetPrefix; it prevents _next asset
collisions with the marketing zone. Keep the rewrites in the default zone and
use ordinary <a> links when navigating between zones. Do not add
basePath: '/docs' to this app: its route tree and Fumadocs baseUrl already
include /docs, so doing so would publish /docs/docs/... URLs. If a future
deployment needs basePath, first move the route tree to an unprefixed
src/app/[[...slug]] shape and update every generated/link URL together.
Deploy (Vercel)
- Create a Vercel project with Root Directory unset (
.). The workflow invokes Vercel fromdocs/site, so that directory is already the deployment root; setting it again would resolvedocs/site/docs/site. Leave automatic Git deployments disabled so this workflow remains the only deployment path. - Framework preset: Next.js. This package's
engines.nodeselects Node.js 24 for Vercel builds and functions.vercel.jsonpins install (pnpm install --frozen-lockfile) and build (pnpm build) over the dashboard settings; this package has its own lockfile beside the root workspace. - Set GitHub Actions secrets (required by the production deploy job):
VERCEL_TOKENVERCEL_ORG_IDVERCEL_PROJECT_ID(docs project, not the marketing site)
- Protect the
docs-productionGitHub environment with required reviewers and custom deployment branch policies formainandv*tags. The release-cut dispatch runs frommain; the direct published-release fallback runs from a stable tag, while the workflow still authorizes only exact stable tags. - Prepare the three rewrites above in the
orca.devmarketing project, but leave them disabled until the docs deployment is verified. A Vercel custom domain cannot delegate only/docsby itself; the default zone must proxy both page/API/media requests and/docs-staticassets. Keep the marketing project's old docs routes available for rollback during the transition; putting the proxy rules inbeforeFilesensures they win once enabled. - Deploy a stable desktop tag that contains
docs/site, verify the docs origin, then enable the marketing rewrites. Tags cut before this package was added cannot bootstrap the docs project because production intentionally checks out the tag's exact commit. Remove the old marketing docs routes in a follow-up after the proxy is stable.
.github/workflows/docs.yml runs credential-free checks for every pull request.
It intentionally does not deploy PR previews: a PR-controlled build must not
receive Vercel credentials. A maintainer can add a separate trusted preview
workflow later. Production deploys only from an authorized stable desktop release: an exact
vX.Y.Z tag, a published non-prerelease release, and the
github-actions[bot] release author. Manual dispatch must run from the default
branch and name an existing release that meets the same checks. Mobile,
prerelease, draft, and human-authored releases are skipped. Fork pull requests
remain build-only because GitHub does not expose deployment secrets to fork
jobs.
Versioning
versioning.config.ts keeps the current unversioned /docs URLs stable while
reserving content/versions/<id> for future snapshots. Versioned routes are not
live yet; when they are needed, add the corresponding loader/routes and a
version entry. The release workflow can then deploy them without a trigger
change.
Isolation from the desktop app
- Own
package.json+pnpm-lock.yamlunderdocs/site/ - Not listed in the root
pnpm-workspace.yaml; its ownpnpm-workspace.yamlmakes it a separate workspace root and holds its pnpm settings, which pnpm 12 ignores under--ignore-workspace - Engineering notes remain in repo-root
docs/— do not confuse with this package