holaOS (Agent Skills)

# Repository Guidelines

## User Requirements
- Always use Context7 MCP for library/API documentation, code generation, setup steps, and configuration guidance without requiring an explicit user prompt.

## Icons (desktop renderer)
- Every icon in `apps/desktop/` goes through `@/components/ui/icons` — a thin wrapper layer around `@hugeicons/core-free-icons`. **Never** import from `lucide-react` (the package is removed) and **never** import from `@hugeicons/core-free-icons` directly inside a feature file.
- Need a new glyph? Add the wrapper to `apps/desktop/src/components/ui/icons.tsx` via the existing `makeIcon(SomeHugeicon)` helper, then import it from `@/components/ui/icons`. Single icon vocabulary, one-file swap.
- Use `IconType` (exported from `ui/icons.tsx`) for "component-typed" icon slots (the project's stand-in for lucide's `LucideIcon`).
- Default `strokeWidth` is `1.75`. The sidebar nav rail rebinds locally to `2`. Per-call `strokeWidth` overrides always win.
- "More / overflow" affordances use the plain three-dot `MoreHorizontal` (no surrounding circle).

## Commit & Pull Request Guidelines
Commit history follows Conventional Commits (`feat:`, `fix:`, `migrate:`, `chore:`, etc.) and must use a detailed, structured message format.

Commit message format:
1. First line: `<type>: <imperative summary>` scoped to one cohesive concern.
2. Blank line.
3. Bullet list describing what changed and why (APIs, models, migrations, deletions, wiring changes, behavior changes).
4. Include validation coverage in the body when relevant (tests/lint/commands run).

Example pattern:
```text
feat: add cronjobs API and expand proactive analyst bootstrap context

- add a new FastAPI cronjobs service with health and CRUD/list endpoints
- add typed cronjobs client helpers and API-key handling
- update proactive analyst bootstrap context to include profile cronjobs
- add/adjust tests for API, client, and prompt behavior
```

PRs should describe context, validation commands (e.g., `make check`, `npm run runtime:test`), linked issues, and screenshots/log excerpts for API or UI-affecting work. Highlight any Supabase branch or migration impacts and note required environment tweaks.

# holaOS — repo guide

The local Electron desktop app (`hola-boss-oss`) + its in-process runtime
(`runtime/{harnesses,harness-host,api-server,state-store}`). See
`apps/desktop/CLAUDE.md` for desktop-renderer conventions and the parent
`~/Developer/CLAUDE.md` for how this fits the wider Holaboss product.

## `hola` — debug the Hola (pi) brain from the CLI

`scripts/hola.mts` runs the **pi (Hola)** harness **in-process from source** so you
can debug the brain without the desktop UI: breakpoints in `runtime/harness-host/src/pi.ts`,
edit-and-rerun with no build/stage loop, and spin up multiple instances.

```bash
# Close the desktop for THIS checkout first (see "why" below), then:
npm --prefix runtime/api-server run hola -- -p "list the files in this repo and summarize it"
```

How it works: it calls the runtime's real `executeTsRunnerRequest` pipeline and
overrides only the `runHarnessHost` dep to run `runPi()` in-process instead of
spawning `harness-host run-pi`. So every build stage (MCP, sidecar, skills,
tools, `model_client`, injected context) is **faithful** to a desktop run; only
the harness subprocess is swapped. Events stream through the real relay (so
`harness_session_id` is persisted → resume works) and are pretty-printed.

Key facts:
- **Root auto-detected** from `apps/desktop/.env` (`HOLABOSS_DESKTOP_USER_DATA_DIR`
  → `<appData>/<dir>/sandbox-host`, same as the desktop). Override with
  `--sandbox-root <path>` or `HB_SANDBOX_ROOT`.
- **Owns the root runtime** ("option 1"): run with the **desktop closed** on that
  root. The tool refuses a root whose `data.db-wal` is hot (a live desktop) unless
  `--force` — opening a live root's `data.db` risks write contention. Each `hola`
  run launches/reuses a runtime backend (for the HTTP-backed tools: runtime-agent
  tools / composio / browser / web-search); `--no-runtime` skips it (brain + model
  + workspace MCP still work).
- Creds: `model_proxy_api_key` is the **auth token**, `sandbox_id` from
  `resolveProductRuntimeConfig()` (reads the root's `state/runtime-config.json`) —
  so it reuses your desktop login; no separate auth.

Flags: `-p/--prompt`, `--cwd`, `-m/--model`, `-s/--session <path>` (resume a
specific session; default auto-resumes the workspace's last one), `--fresh`
(new session, won't overwrite the saved one), `--no-runtime`, `--keep` (leave the
launched runtime up), `--force`, `--print-request` (build + print, no model
call — still opens the DB), `--debug` (raw events), `--port`.

Implementation notes for future edits:
- The file is `.mts` (forces ESM; `ts-runner.ts` has a top-level await that breaks
  CJS transform) and lives in `scripts/` (outside every package's `tsconfig` so it
  never pollutes `tsc --noEmit`). Run via the api-server's `tsx`. `prehola` rebuilds
  better-sqlite3 for the current node ABI.
- `runPi(req, deps)` REPLACES its deps — pass `{ ...defaultPiDeps(), emitEvent }`,
  not just `{ emitEvent }`, or you'll hit `deps.createSession is not a function`.
- Apply the root env (`HB_SANDBOX_ROOT` + DB paths) BEFORE launching the runtime
  child, else it defaults to `/holaboss` and dies with `mkdir: /holaboss:
  Read-only file system`.