# 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`** | API URL, key, model, 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.

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

Provider profile notes:

- `groq` profile defaults to `https://api.groq.com/openai/v1` and OpenAI-compatible chat completions/tool calling semantics.
- `xai` profile defaults to `https://api.x.ai/v1` with reasoning-summary/event compatibility handling.

## 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.