@aiworker/web 1.22.0 → 1.22.2

package/server/lib/session-assist/DOCUMENTATION.md.bak

@@ -1,66 +0,0 @@
-# Session Assist
-
-Server-side watcher that generates a short recap of the agent's last reply
-and one suggested user follow-up with the small model
-(`lib/small-model`), storing both on the session's metadata under
-`metadata.aiworker.assist`.
-
-## Flow
-
-1. `createSessionAssistRuntime` is a consumer of the server's global SSE
-   fan-out (`index.js` → `onPayload`), riding the same upstream connection as
-   notifications. Purely event-driven — dormant sessions never generate
-   anything, there is no backfill and no session scanning.
-2. `session.status: idle` arms a 60-second per-session timer; any `busy`/
-   `retry` status or a user `message.updated` clears it (the "1 minute of
-   quiet" rule).
-3. On fire: fetch the session (skip sub-agent sessions with `parentID`),
-   take the LAST exchange only — the final assistant reply plus the user
-   message it answered (assistant `parentID` → user id) — and call
-   `generateSmallModelText` with the
-   session's own provider/model taken from the last assistant message — so
-   the utility call spends the same subscription as the conversation.
-   `restrictToPreferredProvider` forbids the resolver's global fallback:
-   conversation content never goes to a provider the user didn't pick for
-   the session, unless the small model was chosen explicitly (settings
-   override or opencode config). A resolver 404 is silently skipped.
-4. The requested JSON fields (`recap`, `suggestion`, or both) are clamped and
-   PATCHed onto the session metadata together with `forMessageID` (the last
-   assistant message id) and `generatedAt`. Before writing, the session tail is
-   re-checked (a stale result is dropped) and the metadata is merged from a
-   fresh session read so concurrent metadata writes made during generation are
-   preserved.
-
-## Settings gate
-
-`sessionRecapEnabled` and `sessionSuggestionEnabled` in AiWorker settings
-(Settings → Chat, default on) are hard generation switches checked at fire
-time. When both are off, no small-model calls run and nothing is written. When
-one is on, the runtime still makes at most one small-model call and asks only
-for that field. The UI also hides disabled payload types immediately.
-
-## Freshness contract (no clearing writes)
-
-Clients do not need the payload to be deleted: they render it only while
-`assist.forMessageID` still equals the session's last assistant message id
-(and the session is idle). Any new message invalidates the payload
-everywhere instantly and offline; the next idle cycle overwrites it.
-
-## UI consumers (packages/ui)
-
-- `lib/sessionAssistMetadata.ts` — payload parsing.
-- `hooks/useSessionAssist.ts` — freshness gating + the 1-minute quiet window
-  for the recap (single timeout to the boundary, no polling).
-- `components/chat/SessionRecapSpacer.tsx` — renders the recap inside the
-  fixed-height reserved gap under the last message (height never changes).
-- `components/chat/SessionSuggestionChip.tsx` — one tappable suggestion chip
-  near the composer (desktop chips row + above the mobile pill); hidden as
-  soon as the composer has any content. Tap fills the input, never sends.
-
-## Limitations
-
-- The watcher lives in the web server, so VS Code (extension-only, no web
-  server) does not generate assists; it still renders payloads produced by a
-  web/desktop instance of the same OpenCode server via `session.updated`.
-- Metadata payloads ride every `session.updated` event — keep the clamps
-  (`RECAP_CHAR_LIMIT`, `SUGGESTION_CHAR_LIMIT`) small.

package/server/lib/session-goal/DOCUMENTATION.md.bak

@@ -1,213 +0,0 @@
-# Session Goal
-
-Server-side control loop that keeps a session working toward a user-defined
-objective stored under `metadata.aiworker.goal`, with the small model as
-an independent progress auditor. Built on AiWorker's backend-driven
-architecture (session-assist is the structural template): the loop lives in
-the web server and survives UI disconnects.
-
-## Goal payload (`metadata.aiworker.goal`)
-
-```
-{
-  id,                      // opaque per-logical-goal id; stale-write guard
-  objective,               // inline user text (fallback), <= 5000 chars
-  objectiveFile,           // true: objective text lives in a server-side file
-  status,                  // active | paused | blocked | budgetLimited | complete
-  tokenBudget,             // optional positive int
-  tokensUsed,              // tokensCommitted + current segment (snapshot - baseline)
-  tokensBaseline,          // segment start snapshot (pre-goal turn; 0 after compaction)
-  tokensCommitted,         // closed segments' total (one segment per compaction)
-  turnsUsed,               // auto-continuations sent (capped at MAX_AUTO_TURNS)
-  blockedStreak,           // consecutive blocked audit verdicts
-  auditFailStreak,         // consecutive failed/unavailable audit calls
-  note,                    // latest audit progress note, <= 280 chars
-  statusReason,            // why settled; 'resumed' is a kickoff signal from UI
-  evaluationProviderID,    // provider used by the latest successful audit
-  evaluationModelID,       // model used by the latest successful audit
-  lastAccountedMessageID,  // incremental accounting cursor
-  createdAt, updatedAt
-}
-```
-
-The UI writes goals (create/edit/pause/resume/clear) by patching this
-metadata; the runtime never creates a goal on its own. Goal creation happens
-at send time via the arm store (`useSessionGoalArmStore`): the composer
-target button arms "the next prompt is the objective", and the run-as-goal
-flows (fork-from-answer dialog, plan implement dialog) arm the same way —
-the plan flow additionally supplies an objective OVERRIDE carrying the plan
-content, since "Implement this plan: X" alone gives the audit nothing to
-judge against. The armed send also attaches a synthetic system-reminder
-part telling the agent goal mode is active and that each turn should end
-with a factual done/verified/remaining statement for the independent audit.
-Freshness/stale-write protection is by `id`: every runtime write re-reads the
-session and drops the write when the stored goal id no longer matches.
-
-## File-backed objectives
-
-The objective TEXT lives in `<data-dir>/goals/<sessionId>.md` (data dir =
-`AIWORKER_DATA_DIR` or `~/.config/openchamber`), keyed by the SESSION ID:
-sessions are globally unique and carry one goal at a time, so the mapping is
-deterministic and a new goal simply overwrites the file. Metadata carries
-only `objectiveFile: true` — never a path — so user-writable metadata cannot
-become a file-read vector (`objectives.js` also validates the id shape
-before touching the filesystem). Rationale: metadata rides every
-`session.updated`, so multi-KB objectives must not live there.
-
-- `objectives.js` — write/read/delete, 5000-char clamp.
-- `routes.js` — `PUT/GET/DELETE /api/goals/objective/:sessionId`
-  (AiWorker-owned, registered before the generic proxy; JSON parsing via
-  the `/api/goals` family in core-routes). The UI writes the file BEFORE
-  patching the goal metadata and falls back to an inline objective when the
-  write fails; `clearSessionGoal` deletes the file best-effort.
-- The tick resolves the effective objective fresh on every cycle (the file
-  is live-editable mid-goal) and falls back to the inline `objective` when
-  the file is unreadable — a goal never dies because a file went away.
-- UI display fetches content via the GET route
-  (`useGoalObjectiveContent`); in VS Code the route is unavailable, so the
-  strip degrades to the audit note (display-only fallback by design).
-- Server-created goals write the file through `create.js`, which also owns
-  objective fitting, inline fallback, metadata creation, and the synthetic
-  first-turn reminder shared by scheduled tasks and CLI-created sessions.
-
-## Flow
-
-1. `createSessionGoalRuntime` subscribes to the global SSE hub (same pattern
-   as session-assist — it needs the envelope's `directory`).
-2. `session.status: idle` arms a 15s per-session timer; `busy`/`retry` clears
-   it. A `session.updated` carrying a fresh active goal (`turnsUsed === 0` or
-   `statusReason === 'resumed'`) arms a kickoff timer — 3s for fresh goals,
-   ~250ms for an explicit Resume so the nudge feels immediate — since setting
-   a goal on an idle session emits no status transition.
-3. On fire (`tick`), gated by the `sessionGoalEnabled` setting:
-   - fetch session (skip sub-agent sessions), require an `active` goal;
-   - authoritative live-activity check after the quiet window: re-read the
-     session status map, bail if the parent resumed, then list direct child
-     sessions and bail while any child is `busy`/`retry`. A background
-     subagent leaves its parent idle, then injects its result into the parent
-     when done; that parent `busy` → `idle` cycle re-arms the loop without
-     polling. Status/children fetch failure is unknown, not empty, so it skips
-     the audit and retries after another quiet window;
-   - quiescence check via the message tail (trailing user message or
-     unfinished assistant reply → bail; the next idle transition re-arms);
-   - token accounting as a SNAPSHOT of the latest completed assistant turn:
-     `input + cache.read + output`. Earlier turns' inputs and outputs fold
-     into the next turn's cache, so the latest snapshot already carries the
-     whole run's paid tokens — no summing across messages. Goal-relative via
-     `tokensBaseline` (the same snapshot of the newest pre-goal turn,
-     captured on the first tick). Compaction (an assistant message with
-     `summary: true`) breaks the snapshot chain, so accounting is segmented:
-     the summary message closes the segment into `tokensCommitted` (the
-     summary turn read the whole context, so its snapshot prices the
-     compaction itself) and the next segment starts with a zero baseline.
-     `tokensUsed = tokensCommitted + current segment`, kept monotonic so
-     unflagged context shrinks never move the budget backwards;
-   - a user abort pauses the goal instead of blocking it: the event path in
-     `processPayload` pauses immediately on the MessageAbortedError message
-     (before any tick could send a continuation over the user's explicit
-     stop), with a tick-side safety net. Messages sent while paused leave
-     the goal alone; Resume re-arms the loop, and resuming over an aborted
-     tail skips the audit and goes straight to a continuation nudge;
-   - terminal checks, cheapest first: assistant turn error → `blocked`;
-     `tokensUsed >= tokenBudget` → `budgetLimited`;
-     `turnsUsed >= MAX_AUTO_TURNS` (20) → `blocked`;
-   - if the latest message is a compaction summary, skip the audit and
-     continue unconditionally — running into the context window mid-work is
-     by definition "in progress, not finished" (the summary is a retelling,
-     not evidence, and must not be judged);
-   - otherwise, small-model audit of the objective + the last assistant turn
-     only — no conversation history and no continuation prompts
-     (`restrictToPreferredProvider`, session's own provider/model preferred):
-     JSON `{verdict: continue|complete|blocked, note}`. The audit is the SOLE
-     termination authority besides the hard stops above — the working agent
-     has no channel to settle its own goal. `complete` settles; `blocked`
-     increments `blockedStreak` and settles only after 3 consecutive blocked
-     verdicts, so a one-off snag cannot end the goal. Audit failure/absence
-     tolerates ONE consecutive unaudited continuation (`auditFailStreak`); a
-     second consecutive failure settles the goal as `blocked` ("progress
-     audit unavailable") — resumable, and settling resets the streak so
-     Resume gets fresh tolerance. A dead small model can never drive the
-     loop blind to the turn cap;
-   - continue: persist accounting + `turnsUsed` first (a crash after the
-     write just waits for the next idle tick; the reverse could double-send),
-     re-check the tail, then `POST /session/:id/prompt_async` with the
-     continuation prompt using the last assistant message's
-     provider/model/agent — the goal spends the session's own subscription.
-4. Settling (`complete`/`blocked`/`budgetLimited`) fires the injected
-   `emitGoalNotification` so the user hears about it even with the UI closed:
-   desktop + UI broadcast + the standard push fanout (web-push with full
-   text; APNs with a generic per-type title and the session name as body).
-   It obeys the notify-on-completion setting. Conversely, while a goal is
-   ACTIVE the notifications runtime suppresses per-turn "ready"
-   notifications on every channel — they would only echo the loop's own
-   continuations; error/question/permission notifications are untouched.
-   Pausing a goal from the UI also aborts the running turn (and vice versa —
-   an abort pauses the goal), so "stop" means stop on both axes.
-
-## Continuation prompt
-
-Built inline in `runtime.js`: the objective as untrusted user data in an
-XML-escaped `<objective>` block, budget numbers, keep-the-full-objective and
-work-from-evidence rules, a completion-audit instruction, and the requirement
-to end every turn with a factual done/verified/remaining report — the audit
-sees only that final turn, so the report is its evidence.
-
-## UI consumers (packages/ui)
-
-- `lib/sessionGoalMetadata.ts` — payload parsing/types.
-- `lib/sessionGoalActions.ts` — create/edit/pause/resume/clear via
-  `patchSessionMetadata`; `lib/sessionGoalPresentation.ts` — status
-  colors/labels shared across surfaces.
-- `stores/useSessionGoalArmStore.ts` — the "next prompt starts a goal" flag,
-  consumed by `sendMessage` in `sync/session-ui-store.ts` (works for drafts).
-  Armed slash commands resolve their authoritative command template and apply
-  OpenCode argument expansion (`$ARGUMENTS`, positional placeholders, or the
-  implicit argument suffix) for the audit objective before goal metadata is
-  written and before `session.command` dispatch. If command details cannot be
-  loaded, the raw invocation remains the objective rather than blocking command
-  execution.
-- `hooks/useSessionGoal.ts` — live goal state.
-- `components/chat/SessionGoalButton.tsx` — composer target button
-  (arm / status color / cancel confirm); `SessionGoalRow.tsx` — goal strip
-  above the composer; `SessionGoalDialog.tsx` — manage dialog
-  (edit/pause/resume/complete/clear).
-- Sidebar glyph next to the date in `SessionNodeItem`.
-
-## Scheduled goals
-
-Scheduled tasks can run as goals: `execution.goalEnabled` (+ optional
-`execution.goalTokenBudget`) on a task makes the scheduled-tasks runtime
-stamp `metadata.aiworker.goal` onto the fresh session (objective = the
-expanded task prompt, or the argument-expanded command template for a slash
-command) and attach the goal-mode intro part to normal prompts.
-The loop here picks it up from session events like any other goal.
-
-## CLI-created goals
-
-`aiworker session create --prompt <text> --goal` uses the explicit
-`POST /api/openchamber/sessions` orchestration route. The server creates the
-session, fits and stores the expanded prompt as its objective, patches active
-goal metadata, appends the synthetic goal reminder, and only then dispatches
-the prompt. `--goal-token-budget` applies the same optional budget contract as
-scheduled goals. Slash commands retain command dispatch semantics and cannot
-carry the synthetic prompt part. Their command template with OpenCode argument
-expansion becomes the audit objective; goal metadata
-is still installed before the command runs. A missing command template falls
-back to the raw invocation.
-
-`aiworker session send --goal` and `aiworker session fork --goal` use
-the same server-owned prompt orchestration. Send installs a fresh goal on the
-target session; fork first uses the official OpenCode fork operation (at the
-optional message boundary), then installs the goal on the new session. Both
-preserve the objective-file-before-metadata and metadata-before-dispatch
-ordering used by create and scheduled goals.
-
-## Limitations
-
-- Web-server feature: VS Code (extension-only) renders goal state via
-  `session.updated` but does not run the loop.
-- A goal on a session with no assistant reply yet starts after the first
-  user exchange completes (no provider/model to continue with before that).
-- `tokensUsed` only counts completed assistant messages seen within the
-  40-message fetch window per tick; extremely long busy stretches between
-  idles undercount (acceptable: budget is a guardrail, not billing).

package/server/lib/session-knowledge/DOCUMENTATION.md.bak

@@ -1,89 +0,0 @@
-# Session Knowledge
-
-What a session must be told about the project — that session's pinned notes and
-plans, and the index of what the agent has remembered — and whether it has been
-told yet.
-
-## Why it is here and not in the UI
-
-The client used to own this: it assembled the text, decided when to send it, and
-remembered what it had sent in a module-scoped map. Two consequences followed.
-
-A session started without a UI got nothing at all. Scheduled tasks and sessions
-the agent dispatches build their prompts on the server and never touch the
-browser, so pinned context and the memory index simply did not exist for them.
-
-And a tab's memory of what it sent survives compaction, while the conversation
-does not. After a summary the agent no longer holds the block, but the tab goes
-on believing it does and never sends it again.
-
-## The contract
-
-`session.metadata.aiworker.project_context_pins` owns the note and plan ids
-attached to that session. Pins never come from project-wide note or plan state.
-A new-session draft passes its pins into this metadata when its first message
-creates the session.
-
-Directories beneath the managed `~/.config/openchamber/chats` root resolve to that root before project context and project memory are read. Every ordinary chat therefore shares one Chats knowledge owner instead of creating an unreachable context store for each dated session directory.
-
-`session.metadata.aiworker.knowledge_context_delivered` holds the signature
-of what the session is carrying. It lives with the session, so it survives the
-tab closing and is visible to every sender, including the ones with no tab.
-
-The signature covers content revisions, not just identity: editing a pinned note
-must re-send it, not merely renaming one.
-
-## Three moments, two deliveries
-
-| Moment | Delivery |
-|---|---|
-| A message from the UI | synthetic part on that message |
-| A scheduled task, a session the agent dispatched | synthetic part on that prompt |
-| After compaction | its own `prompt_async`, alongside the pinned messages |
-
-The first two attach to an outgoing message because there is one. Compaction has
-none, which is why it re-sends on its own — and it travels with
-`context-obligatory`'s pinned messages in a single turn, since two synthetic
-messages back to back read as the agent being interrupted twice.
-
-## Failure behaviour
-
-Nothing here may fail a send. A message without its background costs the agent
-some context; a failed send costs the user their message. Every caller treats an
-error as "no block this time".
-
-A source that will not load never blanks the rest: an unreadable memory store
-still delivers the pinned notes. A memory scope that failed to load is left out
-rather than indexed as empty, which would teach the agent to store again what it
-already has.
-
-Delivery is recorded only after the send is accepted. Recording it when the text
-is handed over would leave a failed send believing the agent had context it never
-received.
-
-## Entries that read as instructions
-
-Memory is the one place where text from outside can settle permanently. The
-agent reads a page, decides a line is worth keeping, saves it — and from then on
-it rides into every session in every project. An injection anywhere else lives
-for one conversation.
-
-`agent-memory/threat-patterns` scans on write and again on every read, so an
-entry written before a pattern existed, or edited on disk since, is judged now.
-A match never deletes: the entry is stored, flagged, kept out of what sessions
-are told, and shown in the panel with a warning. Silently dropping it would hide
-the attempt from the only person able to judge it.
-
-Patterns, not a model — this runs on every index build. That buys the blunt
-cases only, which is the honest expectation.
-
-## Shipping dark
-
-Agent memory is complete but unreleased. `AIWORKER_MEMORY_ENABLE` decides
-whether it exists in a given process at all: unset, there is no tool, no routes,
-no session index, no settings row and no panel tab — absent rather than switched
-off, which would invite turning on something never announced. The setting itself
-also defaults to off, so setting the variable does not enable memory by itself.
-
-Pinned notes and plans are unaffected by the memory switch and remain scoped to
-the session that pinned them.

package/server/lib/skills-catalog/DOCUMENTATION.md.bak

@@ -1,151 +0,0 @@
-# Skills Catalog Module Documentation
-
-## Purpose
-This module provides skill discovery, scanning, and installation capabilities for OpenCode. It supports skill sources backed by git repositories, with caching and conflict resolution for skill installation.
-
-## Entrypoints and structure
-- `packages/web/server/lib/skills-catalog/`: Skills catalog module directory containing all skill-related functionality.
-  - `cache.js`: In-memory cache for scan results with TTL support.
-  - `curated-sources.js`: Predefined skill sources (Anthropic, OpenAI, Cursor, Matt Pocock).
-  - `github-meta.js`: Best-effort GitHub repository metadata (stars, last push) with in-memory TTL cache.
-  - `git.js`: Git operations helpers for cloning and auth error detection.
-  - `install.js`: Skills installation from git repositories.
-  - `scan.js`: Skills scanning from git repositories.
-  - `source.js`: Source string parsing for git repositories.
-
-## Public API
-
-The following functions are exported and used by the web server:
-
-### Cache (`cache.js`)
-- `getCacheKey({ normalizedRepo, subpath, identityId })`: Generate cache key for scan results.
-- `getCachedScan(key)`: Retrieve cached scan result if not expired.
-- `setCachedScan(key, value, ttlMs)`: Store scan result with TTL (default 3 hours).
-- `scanWithCache(key, loader, { refresh })`: Run a scan loader with cache lookup, in-flight deduplication, and a global concurrency limit (2 concurrent scans); only `ok: true` results are cached.
-- `clearCache()`: Clear all cached scan results.
-- Scan results persist to `skills-catalog-cache.json` in the AiWorker data dir (debounced, atomic rename) and survive server restarts within the TTL.
-
-### Curated Sources (`curated-sources.js`)
-- `getCuratedSkillsSources()`: Return list of curated skill sources (Anthropic, OpenAI, Cursor, Matt Pocock).
-- `CURATED_SKILLS_SOURCES`: Constant array of predefined sources.
-
-### GitHub Repository Metadata (`github-meta.js`)
-- `fetchGitHubRepoMetas(normalizedRepos)`: Fetch `{ stars, repoUpdatedAt }` for GitHub `owner/repo` strings. Best-effort: failures resolve to `null`; in-flight requests deduplicate; results cached in memory and on disk (`skills-github-meta.json`) for three hours.
-- `clearGitHubMetaCache()`: Test-only cache reset.
-
-### Source Parsing (`source.js`)
-- `parseSkillRepoSource(source, { subpath })`: Parse git repository source string into structured object with SSH/HTTPS clone URLs, normalized repo, and effective subpath. Supports SSH URLs, HTTPS URLs, and shorthand `owner/repo[/subpath]` format.
-
-### Git Repository Scanning (`scan.js`)
-- `scanSkillsRepository({ source, subpath, defaultSubpath, identity })`: Scan git repository for skills by cloning and analyzing SKILL.md files. Returns array of skill items with metadata.
-
-### Git Repository Installation (`install.js`)
-- `installSkillsFromRepository({ source, subpath, defaultSubpath, identity, scope, targetSource, workingDirectory, userSkillDir, selections, conflictPolicy, conflictDecisions })`: Install skills from git repository. Supports user/project scopes, opencode/agents targets, conflict resolution (prompt/skipAll/overwriteAll), and sparse checkout for efficiency.
-
-## Internal Helpers
-
-The following functions are internal helpers used by exported functions:
-
-### Git Helpers (`git.js`)
-- `runGit(args, options)`: Execute git command with optional SSH identity, timeout, and max buffer. Returns `{ ok, stdout, stderr, message, code, signal }`.
-- `looksLikeAuthError(message)`: Detect if error message indicates authentication failure (permission denied, publickey, etc.).
-- `assertGitAvailable()`: Check if git is available in PATH.
-
-### Skill Name Validation (used in `install.js`, `scan.js`)
-- `validateSkillName(skillName)`: Validate skill name against pattern `/^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]$/` (1-64 chars, lowercase alphanumeric with hyphens).
-
-### File System Helpers (`install.js`, `scan.js`)
-- `safeRm(dir)`: Safely remove directory recursively (ignores errors).
-- `ensureDir(dirPath)`: Ensure directory exists with recursive creation.
-- `copyDirectoryNoSymlinks(srcDir, dstDir)`: Copy directory contents without symlinks, with path traversal protection.
-- `normalizeUserSkillDir(userSkillDir)`: Normalize user skill directory path (handles legacy `~/.config/opencode/skill` → `~/.config/opencode/skills` migration).
-
-### Git Clone Helpers (`install.js`, `scan.js`)
-- `cloneRepo({ cloneUrl, identity, tempDir })`: Clone git repository with preferred partial clone (`--filter=blob:none`) and fallback. Uses non-interactive mode.
-
-### SKILL.md Parsing (`scan.js`)
-- `parseSkillMd(content)`: Parse YAML frontmatter from SKILL.md content. Returns `{ ok, frontmatter, warnings }`.
-
-### Path Helpers (`install.js`)
-- `toFsPath(repoDir, repoRelPosixPath)`: Convert POSIX path to filesystem path.
-- `getTargetSkillDir({ scope, targetSource, workingDirectory, userSkillDir, skillName })`: Determine target installation directory based on scope (user/project), targetSource (opencode/agents), and skill name.
-
-## Response Contracts
-
-### Scan Skills Repository Response
-- `ok`: Boolean indicating success.
-- `normalizedRepo`: Normalized repo string (`owner/repo`).
-- `effectiveSubpath`: Effective subpath used for scanning (may be from source string or defaultSubpath).
-- `items`: Array of skill items with `{ repoSource, repoSubpath, skillDir, skillName, frontmatterName, description, installable, warnings }`.
-- `error`: Error object with `{ kind, message }` on failure.
-
-### Install Skills Response
-- `ok`: Boolean indicating success.
-- `installed`: Array of installed skills with `{ skillName, scope, source }`.
-- `skipped`: Array of skipped skills with `{ skillName, reason }`.
-- `error`: Error object with `{ kind, message, conflicts? }` on failure. Kinds: `authRequired`, `networkError`, `conflicts`, `invalidSource`, `unknown`.
-
-### Parse Source Response
-- `ok`: Boolean indicating success.
-- `host`: Git host (e.g., `github.com`, `gitlab.com`).
-- `owner`: Repository owner.
-- `repo`: Repository name.
-- `cloneUrlSsh`: SSH clone URL.
-- `cloneUrlHttps`: HTTPS clone URL.
-- `effectiveSubpath`: Subpath for scanning (from source string or options).
-- `normalizedRepo`: Normalized repo string (`owner/repo`).
-- `error`: Error object with `{ kind, message }` on failure.
-
-## Notes for Contributors
-
-### Adding a New Skill Source
-1. Create a new subdirectory under `packages/web/server/lib/skills-catalog/` (e.g., `newsource/`).
-2. Implement `scan.js` with a function that returns `{ ok, items, error? }` matching the SkillsCatalogItem contract.
-3. Implement `install.js` with a function that accepts selections and returns `{ ok, installed, skipped, error? }`.
-4. Add the source to `CURATED_SKILLS_SOURCES` in `curated-sources.js` if it should appear in the default catalog.
-5. Update `packages/web/server/index.js` to import and wire up the new source.
-
-### Skill Name Validation
-- All skill names must match `/^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]$/` (1-64 chars).
-- Skill names are derived from directory basenames for git repos.
-- Invalid names result in non-installable skills with appropriate warnings.
-
-### Git Cloning Strategy
-- Use sparse checkout to minimize clone size: `sparse-checkout init`, `sparse-checkout set`, `checkout HEAD`.
-- Preferred clone uses `--depth=1 --filter=blob:none` for partial clone with fallback to `--depth=1`.
-- Always use non-interactive mode (`GIT_TERMINAL_PROMPT=0`) to avoid hangs.
-- SSH keys are injected via `core.sshCommand` in git config.
-
-### Conflict Resolution
-- Installation checks for existing skills before downloading/cloning.
-- Three conflict policies: `prompt`, `skipAll`, `overwriteAll`.
-- Per-skill decisions override global policy via `conflictDecisions` map.
-- Conflict response includes `{ skillName, scope, source }` for each conflict.
-
-### Cache Management
-- Cache keys include `normalizedRepo`, `subpath`, and `identityId` for isolation.
-- Default TTL is 3 hours for both scan results and GitHub repository metadata.
-- Scan and GitHub metadata caches persist to JSON files in the AiWorker data dir, so app restarts and page refreshes reuse previous results instead of re-hitting GitHub.
-- Scans run through a global concurrency limiter (2 at a time) with per-key in-flight deduplication.
-- The refresh button passes `refresh: true` and bypasses the cache.
-
-### Security Considerations
-- Path traversal protection in `copyDirectoryNoSymlinks`: resolves real paths and checks containment.
-- Symlinks are explicitly rejected to prevent escape from skill directory.
-- SSH key paths are trimmed but not escaped in `git.js` (assumes safe input from profiles).
-- Temporary directories are cleaned up in `finally` blocks.
-
-### Error Handling
-- All exported functions return `{ ok, ... }` result objects, not throw.
-- Error kinds: `authRequired`, `networkError`, `conflicts`, `invalidSource`, `unknown`.
-- Use `looksLikeAuthError` to detect SSH/HTTPS auth failures for better UX.
-- Log errors to console for debugging but return structured errors to callers.
-
-### Testing
-- Run `bun run type-check`, `bun run lint`, and `bun run build` before finalizing changes.
-- Consider edge cases: non-existent repos, private repos without auth, missing SKILL.md files, invalid skill names, conflicts, network failures.
-
-## Verification Commands
-- Type-check: `bun run type-check`
-- Lint: `bun run lint`
-- Build: `bun run build`