mars-agents 0.2.9

Agent package manager for .agents/ directories
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134

# Bootstrap Docs

Bootstrap docs are setup instructions that skills or packages ship alongside their agents and skills. When a user runs `meridian bootstrap`, an agent session launches with all installed bootstrap docs injected into the system prompt. The bootstrap agent reads the instructions and walks the user through setup — checking installed tools, configuring harness settings, running first-time commands.

Bootstrap docs are read-only prompt context. They are never parsed as executable manifests.

## Two Tiers

Bootstrap docs come from two sources, loaded in this order:

1. **Skill-level** — `skills/<name>/resources/BOOTSTRAP.md` in a source package
2. **Package-level** — `bootstrap/<doc-name>/BOOTSTRAP.md` in a source package

### Skill-level bootstrap docs

Place a `BOOTSTRAP.md` inside a skill's `resources/` directory:

```
skills/my-skill/
  SKILL.md
  resources/
    BOOTSTRAP.md       # setup instructions specific to this skill
    other-resource.md  # other skill resources, unaffected
```

During `mars sync`, skill-level bootstrap docs copy to native harness directories alongside other skill resources:

```
.mars/skills/my-skill/resources/BOOTSTRAP.md       # canonical
.claude/skills/my-skill/resources/BOOTSTRAP.md     # native copy
.codex/skills/my-skill/resources/BOOTSTRAP.md      # native copy
```

This makes skill-level bootstrap docs visible to standalone mars users who read skill directories directly.

### Package-level bootstrap docs

Place a `BOOTSTRAP.md` inside a named subdirectory of `bootstrap/`:

```
bootstrap/
  image-generation/
    BOOTSTRAP.md       # e.g. instructions to enable image_generation in ~/.codex/config.toml
  workspace-setup/
    BOOTSTRAP.md       # e.g. instructions to configure workspace roots
```

During `mars sync`, package-level bootstrap docs sync to `.mars/bootstrap/`:

```
.mars/bootstrap/image-generation/BOOTSTRAP.md
.mars/bootstrap/workspace-setup/BOOTSTRAP.md
```

Package-level bootstrap docs are **not** copied to native harness directories. They are consumed by Meridian at launch time only.

### Manifest-declared bootstrap docs

Bootstrap docs can also be declared in package manifests instead of discovered from `bootstrap/<doc-name>/BOOTSTRAP.md`.

Supported declarations:

```toml
bootstrapDocs = ["./docs/global-auth"]
bootstrap_docs = ["./docs/workspace-setup"]

[package.bootstrap]
path = "./bootstrap"
```

Each path points to either:

- a bootstrap doc directory containing `BOOTSTRAP.md`
- a bootstrap container directory with child doc directories

## Writing a BOOTSTRAP.md

A bootstrap doc is plain markdown. Write it as instructions for an agent to follow when helping a user set up their environment.

Good bootstrap docs:
- Explain what needs to be configured and why
- Include the exact file paths, config keys, and values to check or set
- Note what the agent should verify before making changes (e.g. "check if X is already enabled")
- Give the agent enough context to explain the change to the user

```markdown
# Image Generation Setup

This skill requires `image_generation` to be enabled in your Codex configuration.

## Steps

1. Check `~/.codex/config.toml` for an `[capabilities]` section.
2. If `image_generation` is not set to `true`, prompt the user to enable it.
3. After the user confirms, add or update:
   ```toml
   [capabilities]
   image_generation = true
   ```
4. Confirm the change was saved.
```

## meridian bootstrap

`meridian bootstrap` launches a normal primary agent session with all installed bootstrap docs injected into the system prompt. No special UI or dedicated walkthrough engine — it's a regular agent session with the right context pre-loaded.

```bash
meridian bootstrap
meridian bootstrap -a my-bootstrap-agent   # use a specific agent profile
meridian bootstrap --model opus            # override model
```

The injected bootstrap docs appear in the system prompt in this order:
1. Skill-level docs, alphabetical by skill name
2. Package-level docs, alphabetical by doc name

Each doc is attributed with a `# Bootstrap: <name>` heading in the injected content.

The `--agent` flag selects which agent profile runs the session. If omitted, Meridian uses the default bootstrap agent from the installed agent catalog.

All standard primary launch flags (`--model`, `--harness`, `--approval`, `--work`, etc.) apply.

## Discovery and sync

Mars discovers bootstrap docs at the same time as agents and skills during `mars sync`. Any `bootstrap/` directory in a source package is automatically included; manifest declarations add docs outside that conventional location.

Skill-level bootstrap docs are part of the skill tree and require no extra configuration.

To verify what bootstrap docs are installed after sync:

```bash
ls .mars/bootstrap/                        # package-level docs
ls .mars/skills/*/resources/BOOTSTRAP.md  # skill-level docs
```