Files
orca/docs/site
Kelvin Amoaba a92ec1672d feat(workspace-cleanup): setting to delete Claude Code chats of deleted workspaces (#42959)
* 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.
2026-11-16 21:43:40 +00:00
..

@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.json navigation
  • public/docs/ — docs-only media, logo, and favicon (GIFs, posters, screenshots)
  • src/app/docs/ — fumadocs routes, OG images
  • src/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)

  1. Create a Vercel project with Root Directory unset (.). The workflow invokes Vercel from docs/site, so that directory is already the deployment root; setting it again would resolve docs/site/docs/site. Leave automatic Git deployments disabled so this workflow remains the only deployment path.
  2. Framework preset: Next.js. This package's engines.node selects Node.js 24 for Vercel builds and functions. vercel.json pins install (pnpm install --frozen-lockfile) and build (pnpm build) over the dashboard settings; this package has its own lockfile beside the root workspace.
  3. Set GitHub Actions secrets (required by the production deploy job):
    • VERCEL_TOKEN
    • VERCEL_ORG_ID
    • VERCEL_PROJECT_ID (docs project, not the marketing site)
  4. Protect the docs-production GitHub environment with required reviewers and custom deployment branch policies for main and v* tags. The release-cut dispatch runs from main; the direct published-release fallback runs from a stable tag, while the workflow still authorizes only exact stable tags.
  5. Prepare the three rewrites above in the orca.dev marketing project, but leave them disabled until the docs deployment is verified. A Vercel custom domain cannot delegate only /docs by itself; the default zone must proxy both page/API/media requests and /docs-static assets. Keep the marketing project's old docs routes available for rollback during the transition; putting the proxy rules in beforeFiles ensures they win once enabled.
  6. 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.yaml under docs/site/
  • Not listed in the root pnpm-workspace.yaml; its own pnpm-workspace.yaml makes 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