# 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

Max-autonomy bridge policy switches are also in `config.json`:

- `allow_bridge_mutations` — master mutation gate
- `allow_host_notifications` — notification route gate
- `allow_host_actions` — host action route gate
- `emergency_stop_mutations` — kill switch for mutating bridge tools

Autonomous coding runner controls in `config.json`:

- `autonomous_mode_enabled` — master toggle for autonomous loop mode
- `autonomous_max_runtime_ms` — runtime timebox for autonomous sessions
- `autonomous_completion_required_checks` — quality gates that must pass before done
- `autonomous_allow_paths` — allowed write/shell scope paths (`*` for unrestricted by path policy)
- `autonomous_deny_ops` — hard denylist of tool operations blocked during autonomous runs
- `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.