# Bare OS agent — Markdown workspace

This tree follows the **agent** Markdown workspace convention: “soul” files under **`workspace/`** define personality, rules, and memory. **`/bin/agent`** loads them into the LLM **system prompt** on each session (after seeding from **`/share/agent-workspace/`** on the system drive if `~/.agent/workspace/SOUL.md` is missing).

## Layout (personal Hyperdrive)

| Path | Role |
| --- | --- |
| **`~/.agent/workspace/`** | Agent brain — **git-trackable**, portable across peers |
| **`~/.agent/workspace/skills/`** | Modular **skills** — one folder per skill, each with **`SKILL.md`** (optional YAML frontmatter) |
| **`~/.agent/workspace/memory/`** | Daily append logs `YYYY-MM-DD.md` (optional) |
| **`~/.agent/skills/`** | Optional **global** skills (lower precedence than `workspace/skills/` when names collide) |
| **`~/.agent/config.json`** | Backend (`qvac` / `rest`), model, API URL/key (REST), and reasoning/process visibility controls |
| **`~/.agent/skill-loader.js`** | Host stub for `discoverSkills` / `loadSkill` (in-image agent uses bundled discovery + **`read_skill`** tool) |
| **`~/.agent/loader.js`** | Stub / hook for **host-side** experimentation (not used by `/bin/agent` bundle) |
| **`~/.agent/index.js`** | Stub factory reference (in-image agent uses built-in loader) |

## Skills

1. Add a directory under **`~/.agent/workspace/skills/<skill-id>/`** with a **`SKILL.md`** file.
2. Use YAML frontmatter for **`name`**, **`description`**, **`version`**, etc. The compact system prompt lists **id**, **name**, and a short **description** only.
3. During a session, the model loads the full document with the **`read_skill`** tool (do not paste huge skills into the user channel unless asked).
4. Shared skills can live under **`~/.agent/skills/`**; keep **`workspace/skills/`** for machine-local or repo-specific behavior.

Seeded examples in this repo (under **`skills/`**): **`p2p-os-status`**, **`bare-os-kernel-proc`**, **`bare-os-super-developer`**, **`agent-ops`**, **`holesail`** (managed **`state.json`**, **`seed`**/**`key`**, stock **`bare-www-*`** / **`bare-ssh-*`**), and **`hdms`** (Hyperdrive mounts and invite/pair). Provider-specific skill **`xai-compat`** is only seeded when `provider` is configured as `xai`.

After **`agent --config`** / **`--setup`** (or changing **`owner_name`** / **`agent_label`** via **`edit_agent_config`**), **`IDENTITY.md`** and **`USER.md`** are regenerated from **`config.json`** so the workspace matches the operator and agent label.

## Inference backends

Default backend is **QVAC** (QuantumVerse Automatic Computer) — local in-process LLM via the booter **`ctx.bareOsQvac*`** bridge (`@qvac/sdk`). Weights download on first use after you pick a profile in **`agent --config`**.

Models are stored for durability on HDMS label **`models`** (guest path **`/mnt/models/`**) and materialize into a host cache for llama.cpp load:

- Host cache: **`$BARE_OS_HOST_DATA/qvac/models`** (default **`~/.bare-os/qvac/models`**)
- Runtime config: **`$BARE_OS_HOST_DATA/qvac/qvac.config.json`** (`QVAC_CONFIG_PATH`, absolute `cacheDirectory`)

First load downloads via the QVAC registry into the **host cache**, then mirrors into HDMS. If HDMS already has the GGUF, Bare OS materializes it to the host cache before load. If auto-create fails, run **`hdms create models`** after unlock.

- `backend` — `qvac` (default) or `rest`
- `qvac_profile` — `lite` / `recommended` / `strong` / `tool-tiny`
- `qvac_model` — registry id (e.g. `QWEN3_1_7B_INST_Q4`)
- `qvac_ctx_size` — optional advanced override (≥ profile model-card size). Defaults are automatic from model cards (Qwen3 **32768**, Llama tool-tiny **131072**). Legacy 4k/8k values are ignored. Cap further with host env `BARE_OS_QVAC_MAX_CTX` if VRAM is tight.
- `agent --config` only asks for **owner name**, **agent label**, and **QVAC vs REST**; model/profile/context are applied automatically.
- `qvac_device` — `gpu` (default) or `cpu` (bypass Vulkan; slower)
- `qvac_main_gpu` — `auto` (default: pick highest-VRAM Vulkan GPU, else CPU), `dedicated`, `integrated`, or device index (`0`, `1`, …)
- `qvac_gpu_layers` — optional layer offload count (`0` = CPU weights)

Set **`BARE_OS_SKIP_QVAC=1`** on the host (or pack with **`--skip-qvac`**) to stub QVAC natives; then choose **REST** in config.

REST (OpenAI-compatible) remains fully supported:

- `rest_base_url`, `rest_api_key`, `model`, `provider` (`groq` / `xai` / …)
- `groq` profile defaults to `https://api.groq.com/openai/v1`
- `xai` profile defaults to `https://api.x.ai/v1`

Reasoning/process visibility is configurable in `config.json`:

- `show_reasoning` — master toggle
- `reasoning_mode` — `off` / `summary` / `trace`
- `reasoning_max_chars` — bounded reasoning output
- `reasoning_include_tools` — include tool traces in process stream

The seeded **SOUL.md** / **AGENTS.md** / **TOOLS.md** tell the model it is a coding agent with full guest admin (denylist): unique `search_replace`, `apply_patch`, `grep` (`output_mode`), `find_symbol`, `glob_files`, `todo_write`, plan mode, memory / `remember`, skills / `create_skill`, `web_search`, git helpers, session rewind/export, and `run_js_script` (no Node in the guest). Project skills are also walked from `.grok/skills`, `.agents/skills`, `.claude/skills`, and `.cursor/skills`.

CLI production flags: `--plan`, `--auto`, `--new`, `--compact`, `--max-turns`, `--model`, `--system FILE`. Inspect (no model call): `skills` / `todos` / `plan` / `undo` / `hooks` / `history [query]` / `rewind [N]` / `export [path]` / `remember TEXT` / `recap`. Discord `/agent` is the same harness (shared `~/.agent`).

Access policy defaults to **full guest admin** (`access_policy: full`):

- `allow_delete`, `allow_bridge_mutations`, `allow_host_notifications`, `allow_host_actions` — **true**
- `command_deny` — empty substring denylist for `run_command`
- `mutate_deny_prefixes` — read-only base system (`/bin`, `/etc`, `/boot`, `/lib`, `/usr`, `/share`, `/proc`, `/dev`, `/sys`, `/run`)
- `autonomous_deny_ops` — empty
- `emergency_stop_mutations` — kill switch (default false)

Autonomous coding runner controls in `config.json`:

- `autonomous_mode_enabled` — master toggle for autonomous loop mode (default true)
- `autonomous_max_runtime_ms` — runtime timebox for autonomous sessions
- `autonomous_completion_required_checks` — quality gates that must pass before done
- `autonomous_allow_paths` — optional extra path scope (`*` default; denylist is `mutate_deny_prefixes`)
- `autonomous_deny_ops` — tool-name denylist during autonomous runs (empty by default)
- `autonomous_active`, `autonomous_stop_requested`, `autonomous_status`, `autonomous_last_error` — run state/status fields managed by tools/runtime

## Editing

1. Change files under **`~/.agent/workspace/`** on your **personal** drive.
2. Restart **`agent`** or start a new session so the system message reloads.
3. Keep **`SOUL.md`** / **`AGENTS.md`** stable within a session if you follow the drift guard in **`AGENTS.md`**.

## Defaults in this repository

Source templates: **`packages/bare-os-coreutils/share/agent-workspace/`** — copied to **`kernel/share/agent-workspace/`** during **`npm run build -w bare-os-coreutils`** for seeding into new homes.

## Compatibility

File names and load order match common **agent** Markdown layouts so templates can be dropped into **`workspace/`** with minimal edits.