* feat(workspace-cleanup): delete chat history of deleted workspaces Adds an off-by-default host setting. When on, each cleanup run deletes agent transcripts whose Orca workspace folder no longer exists, through AI Vault's validated delete, and reports the count and space in the run's activity. * fix(workspace-cleanup): keep chat history of folders Orca never made a workspace Skip workspace parents that are or hold a project checkout, protect folders holding a still-listed workspace in any spelling, re-check each folder right before deleting, batch scope paths, count companion bytes, sweep chats at most every 6 hours on hourly runs, and refresh the report when the switch changes. * fix(workspace-cleanup): treat only nested Orca workspace folders as deletable Look for deleted workspaces only in <root>/<repo> of nested layouts, protect renamed workspaces' earlier paths, folder workspaces and case variants, use the recorded cwd only, re-check the parent and the setting before each deletion. * fix(workspace-cleanup): protect flat workspaces and per-host rows from the chat sweep Drop parents inside a still-listed workspace, also read this host's own worktree rows, record a run only when a rule or a due chat sweep has work, and cache per-folder protection with precomputed matchers. * fix(workspace-cleanup): find deleted workspace folders by filesystem identity Walk up from the recorded cwd to the deepest existing folder and require it to be, by device and inode, an Orca <root>/<repo> folder without .git; key protected paths the same way, so symlinks, case and Unicode spellings are the OS's call. A failed history scan no longer fails the run, and an open session history list refreshes after chats are deleted. * fix(workspace-cleanup): close the remaining chat sweep gaps Walk physical ancestors of a symlinked parent, skip a gone folder with a lookalike sibling (parsers trim cwd), re-read listed paths after the scan, never touch WSL paths, use bigint file identity, and report the next run that actually sweeps when only chat history is on. * fix(workspace-cleanup): keep chats resumed elsewhere and follow dangling listed links Before deleting, re-read each transcript: skip it if it was written in the last hour or its last recorded cwd is outside the gone folder (a chat resumed at a live workspace's root). Listed symlinks protect their targets, and parents are re-checked against the listed paths read after the scan. * fix(workspace-cleanup): sweep only Claude chats, whose every message records its cwd Keep a transcript unless its latest recorded cwd, read back past large blobs, is still in the gone folder; agents that record cwd once can't prove a chat wasn't resumed elsewhere. Follow symlinks along listed paths, dangling ones too. * fix(workspace-cleanup): read only a record's own cwd and check each chat right before removal Parse whole JSONL records backwards and use their top-level cwd, not tool arguments; run the setting, folder, idle and last-cwd checks right before each transcript's removal; resolve relative listed links from their real folder. * fix(workspace-cleanup): protect subagent transcripts and re-read listed rows per folder Check a chat's companion transcripts with the same idle and last-cwd rules, read Orca's listed rows right before each gone folder's deletion, keep '..' in listed link targets for the OS to resolve, and say Claude Code in the copy. * fix(workspace-cleanup): fold names fully, keep POSIX repo names, re-stat rows only on change Fold case with upper then lower (final sigma), take the repo name with this host's basename, re-read listed rows per folder only when the catalog changed, and sweep chats even when rule evaluation fails. * fix(workspace-cleanup): re-check the chat itself after walking its companions A chat resumed while its subagent transcripts were being checked has a new size or mtime, so it is kept. * chore(workspace-cleanup): sync localization catalogs and drop a cast in the cwd reader * fix(workspace-cleanup): re-check every subagent transcript after the companion walk Record each companion's version and require the same set, unchanged, before approving deletion; skip the symlink-based sweep test on Windows. * fix(workspace-cleanup): protect chats by what listed paths pass through, checked per chat Each listed path claims the (existing folder, name) pairs along it, so a gone folder holding one stays protected whether that path exists right now or not; claims are re-read before every removal, and an unfollowable symlink chain stops the sweep. * fix(workspace-cleanup): an unreadable folder or a non-directory leaves the sweep fail-closed or ignored A stat error other than absence while reading listed paths marks the snapshot incomplete; ENOTDIR counts as absence instead of stopping every sweep. * fix(workspace-cleanup): check row protection last before each removal and allow exactly eight links Run the slow transcript checks first so the folder and listed-row checks are the freshest before the rm, and resolve the eighth link instead of treating it as an unfollowable chain. * chore(workspace-cleanup): follow the shared settings and execution-host module moves * chore(workspace-cleanup): mark an unreadable identity as undefined, not a string literal * fix(workspace-cleanup): re-read protection when a listed symlink is retargeted Listed paths that go through a symlink record where they led; a different target before a removal re-reads every claim.
@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