dalo 0.8.2

Git-backed skill management for AI agents.
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
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
# Dalo User Reference

This is the user-facing reference for scripting Dalo and for understanding the files Dalo writes. It documents the current CLI and persisted schemas.

## Store Resolution

Dalo chooses the store path in this order:

1. `--store <PATH>`
2. `DALO_STORE`
3. `~/.dalo`

Relative store paths are resolved against the current working directory. `~` is expanded when used at the start of a path.

## Environment Variables

| Variable | Purpose |
| --- | --- |
| `DALO_STORE` | Override the default store path; `--store` takes precedence. |
| `DALO_GIT_TIMEOUT_SECS` | Positive timeout in seconds for every Git subprocess. Invalid or zero values use the built-in defaults. |
| `DALO_OFFLINE` | Disable passive update checks when set to a truthy value. |
| `DALO_UPDATE_CHECK` | Set to `never` to disable passive update checks. |
| `NO_COLOR` | Disable ANSI color output when set. |

For installation variables, see the [README installation section](../README.md#installation)
and the [npm launcher README](../npm/README.md): `DALO_VERIFY`,
`DALO_LINUX_LIBC`, `DALO_TARGET`, `DALO_INSTALL_DIR`, `DALO_VERSION`, and
`DALO_CACHE_DIR`.

## Global Flags

Global flags can be placed before or after the command.

| Flag | Meaning |
| --- | --- |
| `--store <PATH>` | Use a store other than the resolved default. |
| `--json` | Emit machine-readable JSON for commands that support structured output. |
| `--yes` | Reserved for future safe interactive prompts. It is currently a no-op and never implies `--replace`, creates commits, or grants new approvals. |
| `--dry-run` | Plan supported mutating operations without writing files, cloning, linking, or changing locks. Read-only commands ignore it. |
| `-h`, `--help` | Print command help. |
| `-V`, `--version` | Print the installed version. |

## Update Notices

After a successful interactive command, Dalo checks for a newer GitHub release
at most once per 24 hours. The cached check uses a one-second network timeout and
never changes the command's exit status. Checks are skipped for `--json`, CI,
`DALO_OFFLINE=1`, and `DALO_UPDATE_CHECK=never`.

Dalo never modifies its own executable. If the installed version is outdated,
the notice recommends an upgrade command for Homebrew, npm/npx, mise, Cargo, or
the hosted installer. Launchers may set `DALO_INSTALL_CHANNEL` so the Rust binary
can preserve their installation context. Unknown installation methods receive a
link to the installation guide instead of a guessed command. Each newer version
is announced only once per user cache.

## Command Reference

### `dalo init`

Initialize the store layout, default config, local Git source, lock/state files, and approvals file.

Examples:

```sh
dalo init
dalo --store /tmp/dalo-demo init
dalo --json --dry-run init
```

JSON output shape: `InitReport`.

### `dalo target detect`

List known agent targets, their default paths where known, whether those paths exist, and whether they are linked in Dalo state.

Examples:

```sh
dalo target detect
dalo --json target detect
```

Built-in target IDs:

| ID | Default path | Support |
| --- | --- | --- |
| `codex` | `~/.agents/skills` | supported |
| `claude` | `~/.claude/skills` | supported |
| `openclaw` | `~/.agents/skills` | supported |
| `hermes` | `~/.hermes/skills` | supported |
| `generic` | none, path required | supported |
| `cursor` | none | experimental |
| `opencode` | none | experimental |

JSON output shape: `TargetDetectReport`.

### `dalo target link <target> [path]`

Record a target materialization directory. The `generic` target requires an explicit path. Known targets can use their default path or an explicit override.

Examples:

```sh
dalo target link codex
dalo target link generic ./tmp/agent-skills
dalo --dry-run target link claude ~/.claude/skills
```

JSON output shape: `TargetLinkReport`.

### `dalo target unlink <target>`

Disable a target in state. This does not delete skills from the target directory.

Examples:

```sh
dalo target unlink codex
dalo --json target unlink generic
```

JSON output shape: `TargetUnlinkReport`.

### `dalo source add <id> <git-url>`

Add a trusted team source, clone it into `sources/<id>/checkout`, configure it
with `update_policy = "track"`, and run a deterministic security preflight for
every discovered skill. Source IDs must be a single path component using only
letters, digits, `.`, `_`, and `-`; `.` and `..` are rejected.

Examples:

```sh
dalo source add platform git@github.com:example/platform-skills.git
dalo --dry-run source add team https://github.com/example/team-skills.git
```

JSON output shape: `SourceAddReport`.

### `dalo source add-catalog <id> <git-url>`

Add an untrusted catalog source, clone it into `sources/<id>/checkout`, and
configure it with `update_policy = "pin"`. Catalog skills are offers; nothing
from a catalog becomes active until selected and approved.

Examples:

```sh
dalo source add-catalog public https://github.com/example/skill-catalog.git
dalo source inspect public
dalo source select public review-helper
```

JSON output shape: `SourceConfig`.

### `dalo source list`

List configured sources in priority order.

Examples:

```sh
dalo source list
dalo --json source list
```

JSON output shape: `SourceListReport`.

### `dalo source priority <id> <priority>`

Change a source priority. Lower numbers win during resolution. The local source priority is fixed and cannot be changed.

Examples:

```sh
dalo source priority platform 10
dalo --dry-run source priority platform 20
```

JSON output shape: `SourcePriorityReport`.

### `dalo source inspect <id>`

Inspect a catalog source and list available candidate skills, including ID, slot name, path, description, dependencies, and selection status.

Examples:

```sh
dalo source inspect public
dalo --json source inspect public
```

JSON output shape: `CatalogInspectReport`.

### `dalo source select <id> <skill>...`

Select catalog skills by stable frontmatter ID, `<source-id>:<slot>` reference,
or slot name. Selection runs the deterministic security preflight, writes
`config.toml`, and updates `source-lock.toml` with the pinned commit and
inventory snapshot.

Examples:

```sh
dalo source select public review-helper
dalo source select public review-helper formatter
dalo source select public --unselect formatter
dalo --dry-run source select public review-helper
```

JSON output shape: `CatalogSelectReport`.

### `dalo source refresh <id>`

Fetch a catalog source and compare the upstream inventory with the pinned
inventory snapshot. This is read-only for pins and selections. `--check` exits
non-zero when selected skills drifted upstream. Advancing the pin is not
implemented yet.

Examples:

```sh
dalo source refresh public
dalo source refresh public --check
dalo --json source refresh public
```

JSON output shape: `CatalogDrift`.

With `--check`, the command exits with code 1 when a selected skill changed,
moved, or was removed upstream. New unselected offerings remain informational.

### `dalo source remove <id>`

Remove a team or catalog source as one coordinated change. Dalo first reconciles
only links it owns, then removes the source from `config.toml`, its catalog lock
entry (when present), and approvals qualified with that source ID. The source
checkout is removed after the durable store state is committed. Use
`--keep-checkout` to retain it for manual inspection. The built-in `local`
source cannot be removed. A retained checkout must be moved or removed before
the same source ID can be added again.

Examples:

```sh
dalo --dry-run --json source remove platform
dalo source remove public
dalo source remove public --keep-checkout
```

Both dry-run and real `--json` output use `SourceRemoveReport`. It lists
deactivated skills, the operation kind for every reconciled owned link, and any
non-fatal checkout cleanup warnings. Dry-run does not modify config, locks,
approvals, checkouts, or targets.

### `dalo status`

Show source scans, linked targets, active skills, pending approvals, unlinked skills,
user-lock drift, unmanaged target skills, instruction packs, topic overlaps, and
instruction block drift.

Examples:

```sh
dalo status
dalo status --check
dalo --json status
```

JSON output shape: `StatusReport`.

`--check` exits with code 1 for unresolved source scans, inventory warnings,
pending approvals, blocked required closure, missing targets for active skills,
lock drift, unmanaged blockers, or instruction-block drift. It keeps the full
report on stdout for JSON consumers.

### `dalo sync`

Refresh clean tracking team sources, resolve the desired skill set, materialize owned symlinks into linked targets, and write `lock.toml`. Dirty tracking sources block refresh. Dalo does not overwrite unmanaged real directories or foreign symlinks.

Before materialization, Dalo audits the exact content hash of every active
skill. Unaccepted `high` or `critical` findings stop the command before any
links are changed. A previously recorded risk acceptance is reused only while
the complete directory hash, audit-engine versions, coverage, and finding set
remain unchanged.

Tracking team updates are fetched and audited in a detached worktree below
`sources/.audit-staging/` before the live checkout fast-forwards. Existing
target links therefore continue to expose the last accepted commit. When an
update is blocked, the error prints a command for auditing and accepting the
exact staged skill; the next `sync` reuses that staged hash.

Examples:

```sh
dalo sync
dalo sync --check
dalo --dry-run sync
dalo --json sync
```

JSON output shape: `SyncReport`.

`sync --check` still renders the report, then exits with code 1 when materialization
is blocked or incomplete, including pending approvals, resolution diagnostics,
degraded sources, blocked operations, or active skills without linked targets.

An enabled source is **degraded** when Dalo cannot safely scan it, for example
because its checkout is missing or unreadable, a tracking refresh failed, or
inventory warnings make removals ambiguous. Dalo preserves recorded owned links
from that source instead of treating the incomplete scan as a deletion. A normal
`sync` can still apply unrelated safe work and exits successfully; `sync --check`
exits with code 1 until the source is healthy. Restore or re-clone the checkout,
or remove the source with `dalo source remove <id>`. Do not adopt or delete the
preserved target link as if it were an unmanaged conflict.

Lock drift for local and team sources is commit-based. Uncommitted working-tree
edits do not change the recorded commit, and materialized symlinks expose those
live edits directly. Catalog selections are the source kind with content and
metadata fingerprints for upstream drift checks.

### `dalo adopt <skill> [--replace]`

Copy an unmanaged target skill into `local/skills/<slot>`. With `--replace`, Dalo replaces the original unmanaged directory with an owned symlink after copying. Without `--replace`, the original directory remains untouched.

Adoption runs the same deterministic security preflight before copying or
replacing anything. `--agent`, `--refresh-audit`, and `--accept-risk <reason>`
have the same meaning as on `dalo approve skill`.

The `<skill>` argument can be a slot name, a disambiguating path, or an ID reported by `status` or `resolve list`.

Examples:

```sh
dalo adopt review-helper
dalo adopt review-helper --replace
dalo --dry-run adopt /path/to/target/review-helper
```

JSON output shape: `AdoptReport`.

### `dalo resolve list`

List repairable unmanaged skills, target scan warnings, and recorded owned symlinks.

Examples:

```sh
dalo resolve list
dalo --json resolve list
```

JSON output shape: `ResolveListReport`.

### `dalo resolve adopt <id> [--replace]`

Adopt an unmanaged skill by an ID returned from `resolve list`. Behavior matches `dalo adopt`.

Examples:

```sh
dalo resolve adopt review-helper
dalo resolve adopt review-helper --replace
```

JSON output shape: `AdoptReport`.

### `dalo resolve keep <id>`

Protect an unmanaged target skill so Dalo reports it as intentionally unmanaged. Protection is stored by logical target and slot, follows later target-path updates, and turns the sync conflict into a non-failing `keep` operation. An explicit `resolve adopt --replace` remains an override.

Examples:

```sh
dalo resolve keep review-helper
dalo --dry-run resolve keep review-helper
```

JSON output shape: `KeepReport`.

### `dalo resolve unkeep <target>:<slot>`

Remove protection from one target slot. A bare slot name removes matching protection across targets.

Examples:

```sh
dalo resolve unkeep claude:review-helper
dalo --dry-run resolve unkeep review-helper
```

JSON output shape: `UnkeepReport`.

### `dalo resolve remove-owned <id>`

Remove a recorded owned symlink by ID. If the recorded path is already missing, Dalo drops the stale state record. If a real entry exists at that path, Dalo blocks removal.

Examples:

```sh
dalo resolve remove-owned claude:review-helper
dalo --json resolve remove-owned claude:review-helper
```

JSON output shape: `RemoveOwnedReport`.

### `dalo doctor`

Run read-only diagnostics for store layout, config, state, lock, approvals, Git, GitHub CLI, targets, owned symlinks, dirty sources, pending approvals, required closures, instruction packs, and cloud-synced target paths.

Examples:

```sh
dalo doctor
dalo doctor --check
dalo --json doctor
```

JSON output shape: `DoctorReport`.

`--check` exits with code 1 when the report contains an error finding. Warnings
remain report-only so CI can choose its own warning policy.

### `dalo audit <skill-or-path>`

Inspect a skill before it is exposed to an agent. The target can be an existing
directory or a source-qualified reference. Deterministic checks are local and
never execute skill code.

```sh
dalo audit public:review-helper
dalo audit ./my-skill --check
dalo audit public:review-helper --agent auto
dalo --json audit public:review-helper --agent codex
dalo audit public:review-helper --agent claude --refresh-audit
```

Use `--refresh-audit` to ignore a compatible cached semantic review and run the
selected provider again. The older `--refresh` spelling remains a hidden alias
for script compatibility.

`--agent auto|codex|claude|opencode` adds a semantic review through an installed
agent CLI. Dalo starts a fresh non-persistent reviewer and treats a bounded
snapshot as untrusted data. Claude and OpenCode run with tools denied. Codex
currently retains its network-disabled, read-only sandbox shell, so Dalo never
selects it through `auto`; choosing `--agent codex` is an explicit acceptance of
that weaker isolation boundary. User configuration, project rules, skills,
plugins, and MCPs are disabled where the provider supports it. The structured
result contains evidence-backed findings, expected capabilities, and behavior
not disclosed by the skill. Depending on the installed agent configuration,
this can send skill contents to an external model provider and consume that
provider's quota. Dalo never includes `.git` metadata in that snapshot; a skill
containing a `.git` entry receives a blocking, partial-coverage finding instead.
Provider processes receive only an explicit runtime and provider-authentication
environment allowlist rather than inheriting Dalo's full environment. Omitting
`--agent` is fully local.

Agent review is optional and additive, not an approval mechanism. It can add
evidence-backed findings to the deterministic audit, but it never clears a
deterministic finding or certifies a skill as safe. A review with no additional
findings means only that this constrained assessment found no additional issue;
it is not an endorsement or safety guarantee. `sync` does not invoke a provider
on its own.

`--check` exits non-zero for unaccepted `high` or `critical` findings. Record a
reviewed exception with a non-empty reason:

```sh
dalo audit public:review-helper \
  --accept-risk "reviewed pinned upstream installer"
```

Persistence changes (such as shell startup files, scheduled tasks, or agent
configuration) and privileged command execution are `high` findings and block
by default. General dynamic execution remains a `medium` review finding: it is
reported, but does not block materialization on its own. This policy keeps
high-confidence persistence and privilege-escalation primitives behind an
explicit, content-bound risk acceptance without treating every technical skill
as unsafe by default.

Reports live below `audits/` and are keyed by both the source-qualified skill
reference and the complete skill directory hash. Cached agent results
additionally require the same provider and Dalo review-prompt version. Risk
acceptance is bound to source provenance, engine versions, coverage, and exact
deterministic and semantic findings, so a different source or newly discovered
risk requires a new decision even when the skill bytes did not change.

The audit directory and report files are restricted to the current user when
Dalo writes them. Audit state is still a local trust boundary rather than a
cryptographically authenticated log: a process running as the same user can
replace it. Protect the store like other security-sensitive user state and do
not place it in a shared or untrusted writable directory. No-finding results
are best-effort observations, not a security certification.

JSON output shape: `AuditReport`.

### `dalo approve`

Grant, list, and revoke approval records without editing `approvals.toml`.
Every skill, author, and organization value is source-qualified, so an approval
cannot accidentally apply to a different source with the same name.

```sh
dalo approve list
dalo approve skill public:review-helper
dalo approve skill public:review-helper --agent codex
dalo approve skill public:review-helper --accept-risk "reviewed exception"
dalo approve source team
dalo approve author public:maintainers
dalo approve org public:example-org
dalo approve revoke skill public:review-helper
```

Approval writes support `--dry-run` and `--json`. A pending skill shown by
`status` can be approved narrowly with `dalo approve skill <source:skill>`.
Skill approval always runs the deterministic preflight first and refuses a
blocking result unless a reason is supplied with `--accept-risk`. `--agent`
adds the same isolated semantic review as `dalo audit`.

JSON output shapes: `ApprovalsFile` for `list`; `ApprovalReport` for mutations.

### `dalo instructions enable <pack> <file>`

Render a local instruction pack from `local/instructions/<pack>.md` into an instruction file as a managed block. The target file is created if missing. Enabling the same pack again is idempotent and refreshes the block.

Examples:

```sh
dalo instructions enable team-style ~/.codex/AGENTS.md
dalo --dry-run instructions enable team-style ./AGENTS.md
```

JSON output shape: `InstructionPackReport`.

### `dalo instructions disable <pack> <file>`

Remove a pack's managed block from an instruction file and remove its active lock entry.

Examples:

```sh
dalo instructions disable team-style ~/.codex/AGENTS.md
dalo --json instructions disable team-style ./AGENTS.md
```

JSON output shape: `InstructionPackReport`.

### `dalo instructions list`

List active instruction packs recorded in `lock.toml`.

Examples:

```sh
dalo instructions list
dalo --json instructions list
```

JSON output shape: array of `LockedInstructionPack`.

### `dalo completions <shell>`

Generate shell completions to stdout. Supported shell names are provided by `clap_complete`, including `bash`, `zsh`, and `fish`.

Examples:

```sh
dalo completions zsh > _dalo
dalo completions bash > dalo.bash
dalo completions fish > dalo.fish
```

Release archives include generated completions. This command is also available for Cargo installs and local shell setup.

### `dalo manpage`

Generate the `dalo(1)` man page to stdout from the same Clap command definition used for `--help`.

Example:

```sh
dalo manpage > dalo.1
```

Release archives include the generated man page. This command is also available for Cargo installs and local documentation setup.

## Exit Codes

Dalo uses a small scripting contract:

| Code | Name | Meaning |
| --- | --- | --- |
| `0` | success | Command completed. |
| `1` | expected failure | User-actionable input/state problem, such as unknown source, unknown target, unsupported schema, parse error, a failed explicit check, a security-audit block during `sync` or `approve`, or adoption destination already existing. |
| `2` | usage error | Invalid arguments or flags from Clap. This output is plain text even with `--json`. |
| `3` | unsafe state | Dalo refused to mutate because the state needs human attention, such as a dirty source, active store lock, or malformed instruction block. |
| `4` | environment problem | Dependency, path, Git, filesystem, or external command problem. |

Scripts should treat `3` differently from `1`: it means Dalo intentionally stopped before touching state that may require review.

## JSON Output Shapes

`--json` prints one JSON value to stdout on success. Runtime errors are printed to stderr as `{"error":{"code":"...","message":"..."}}` and keep the same exit code as text output. Path fields serialize as strings. Enum fields serialize as `snake_case` unless noted. Commands that mutate and support `--dry-run` include a `dry_run` boolean in their report.

| Command | Shape | Important fields |
| --- | --- | --- |
| `init` | `InitReport` | `store`, `dry_run`, `operations[]` with `action`, `path`, `status` |
| `target detect` | `TargetDetectReport` | `targets[]` with `id`, `name`, `support`, `path`, `exists`, `linked` |
| `target link` | `TargetLinkReport` | `target_id`, `path`, `canonical_path`, `status`, `created_dir` |
| `target unlink` | `TargetUnlinkReport` | `target_id`, `status` |
| `source add` | `SourceAddReport` | `source`, `dry_run`, `audits[]` with one `AuditReport` per discovered skill |
| `source add-catalog` | `SourceConfig` | `id`, `kind`, `path`, `priority`, `enabled`, `trusted`, `url`, `update_policy`, `selection` |
| `source list` | `SourceListReport` | `sources[]` |
| `source priority` | `SourcePriorityReport` | `source`, `dry_run` |
| `source inspect` | `CatalogInspectReport` | `source_id`, `candidates[]` |
| `source select` | `CatalogSelectReport` | `source_id`, `selected[]`, `dry_run`, `audits[]` for skills named by the operation, `migration_warnings[]` for degraded legacy sibling catalogs |
| `source refresh` | `CatalogDrift` | `source_id`, `pinned_commit`, `upstream_commit`, `outcomes[]`, `migration_warnings[]` for degraded legacy sibling catalogs |
| `source remove` | `SourceRemoveReport` | `source_id`, `checkout_path`, `kept_checkout`, `removed_approvals`, `removed_catalog_lock`, `reconciled_links[]`, `deactivated_skills[]`, `cleanup_warnings[]`, `affected_paths[]`, `dry_run` |
| `status` | `StatusReport` | `store`, `sources[]`, `targets[]`, `inventory_warnings[]`, `resolution`, `lock`, `unmanaged_skills[]`, `target_warnings[]`, `instruction_packs[]`, `instruction_pack_overlaps[]`, `instruction_block_drifts[]` |
| `sync` | `SyncReport` | `store`, `dry_run`, `linked_targets`, `operations[]` |
| `audit` | `AuditReport` | `schema_version`, `source_ref`, `skill_path`, `content_hash`, `static_engine_version`, `scanned_at_unix`, `coverage`, `status`, optional `max_severity`, `static_findings[]`, optional `agent_review`, optional `risk_acceptance` |
| `approve list` | `ApprovalsFile` | `schema_version`, `approvals[]` |
| `approve skill` / `source` / `author` / `org` / `revoke` | `ApprovalReport` | `scope`, `value`, `action`, `dry_run` |
| `adopt` / `resolve adopt` | `AdoptReport` | `slot_name`, `source_path`, `local_path`, `copy`, `replacement` |
| `resolve list` | `ResolveListReport` | `unmanaged_skills[]`, `target_warnings[]`, `owned_skills[]` |
| `resolve keep` | `KeepReport` | `skill`, `existing`, `dry_run` |
| `resolve unkeep` | `UnkeepReport` | `selector`, `removed[]`, `dry_run` |
| `resolve remove-owned` | `RemoveOwnedReport` | `id`, `link_path`, `status` |
| `doctor` | `DoctorReport` | `store`, `findings[]`, `summary` |
| `instructions enable` / `disable` | `InstructionPackReport` | `pack_id`, `target`, `action`, `dry_run` |
| `instructions list` | `LockedInstructionPack[]` | `pack_id`, `target`, `source_id`, optional `commit`, optional `version` |

Each `AuditReport.static_findings[]` entry contains `id`, `severity`,
`category`, `path`, optional `line`, `message`, and optional bounded `evidence`.
When present, `risk_acceptance` contains `reason`, `accepted_at_unix`, and
`scope_hash`; `agent_review` identifies the provider and isolation boundary and
includes its findings, summary, expected capabilities/actions, and undeclared
behaviors. `source add` and `source select` expose security preflight results in
their top-level `audits[]` arrays. `source add-catalog` returns only the new
`SourceConfig`: adding a pinned catalog does not audit anything until a skill is
selected.

Common status values:

| Field | Values |
| --- | --- |
| `TargetSupport` | `supported`, `experimental` |
| `TargetLinkStatus` | `planned`, `linked`, `updated`, `existing` |
| `TargetUnlinkStatus` | `planned`, `unlinked`, `missing` |
| `MaterializeOperationKind` | `create`, `relink`, `remove`, `drop_record`, `conflict`, `keep`, `noop` |
| `MaterializeOperationStatus` | `planned`, `applied`, `existing`, `blocked` |
| `AdoptCopyStatus` | `planned`, `copied`, `existing` |
| `AdoptReplacementStatus` | `planned`, `replaced`, `skipped`, `protected` |
| `RemoveOwnedStatus` | `planned`, `removed`, `dropped_missing`, `blocked_real_entry` |
| `InstructionBlockDriftKind` | `missing`, `malformed`, `stale`, `source_missing` |
| `CatalogDrift.code` | `new_available`, `selected_changed`, `selected_moved`, `selected_removed` |
| `TargetScanWarningCode` | `unreadable_target_dir` |

`DoctorFinding` uses:

```json
{
  "severity": "warning",
  "code": "pending_approval",
  "message": "human-readable diagnostic",
  "next_command": "optional next command"
}
```

Doctor severities are `error`, `warning`, `info`, and `ok`.

Resolution diagnostics use these codes when present in `status.resolution.diagnostics`: `pending_approval`, `local_override`, `shadowed`, `required_expanded`, `cross_source_require`, and `required_blocked`. For recovery steps, see [Troubleshooting and FAQ](troubleshooting.md).

## Store Layout

After `dalo init`, the store contains:

| Path | Purpose |
| --- | --- |
| `config.toml` | User-authored config: settings and source list. |
| `lock.toml` | Resolved user lock written by `sync` and instruction commands. |
| `state.toml` | Internal target/materialization/protection state. |
| `approvals.toml` | Local approval records. |
| `source-lock.toml` | Catalog source pins, selections, and inventory snapshots. |
| `audits/<content-hash>-<source-ref-hash>.json` | Source- and content-bound deterministic and optional agent security reports. |
| `.lock` | Temporary coarse lock file while mutating commands run. |
| `local/skills/` | Local private skill directories. |
| `local/instructions/` | Local instruction pack Markdown files. |
| `sources/<id>/checkout/` | Team and catalog Git checkouts. |
| `sources/.audit-staging/` | Detached incoming team commits retained only while security review is required. |

Dalo rejects unsupported schema versions in persisted TOML files.

## `config.toml`

Schema version: `version = 1`.

Example:

```toml
version = 1

[settings]
autosync = false
sync_interval = "hourly"

[[sources]]
id = "local"
kind = "local"
path = "/Users/alex/.dalo/local"
priority = 0
enabled = true
trusted = true

[[sources]]
id = "team"
kind = "team"
path = "/Users/alex/.dalo/sources/team/checkout"
priority = 10
enabled = true
trusted = true
url = "git@github.com:example/team-skills.git"
update_policy = "track"

[[sources]]
id = "public"
kind = "catalog"
path = "/Users/alex/.dalo/sources/public/checkout"
priority = 20
enabled = true
trusted = true
url = "https://github.com/example/catalog.git"
update_policy = "pin"
selection = ["review-helper"]
```

Fields:

| Field | Meaning |
| --- | --- |
| `settings.autosync` | Reserved scheduled-sync switch. |
| `settings.sync_interval` | Optional interval label. |
| `sources[].id` | Stable source ID. |
| `sources[].kind` | `local`, `team`, or `catalog`. |
| `sources[].path` | Local filesystem path for the source root or checkout. |
| `sources[].priority` | Lower numbers win. |
| `sources[].enabled` | Disabled sources are skipped by resolution. |
| `sources[].trusted` | Trusted sources are approved automatically. User-added catalog sources always start untrusted. |
| `sources[].url` | Git URL for team/catalog sources. URLs with embedded credentials are rejected; use SSH or a credential helper. |
| `sources[].branch` | Optional branch label. |
| `sources[].update_policy` | Usually `track` for team sources and `pin` for catalog sources. |
| `sources[].selection` | Catalog selections by stable ID, source ref, path, or slot name. Empty for local/team sources. |

Unknown fields are rejected.

## `approvals.toml`

Schema version: `schema_version = 1`.

Example:

```toml
schema_version = 1

[[approvals]]
scope = "source"
value = "team"

[[approvals]]
scope = "skill"
value = "team:review-helper"

[[approvals]]
scope = "author"
value = "team:platform-team"
```

Approval scopes:

| Scope | Value | Matches |
| --- | --- | --- |
| `skill` | `<source-id>:<slot>` or `<source-id>:<stable-id>` | One skill from one source. Bare slot names and bare stable IDs do not match. |
| `source` | `<source-id>` | Every skill from that source. |
| `author` | `<source-id>:<owner>` | Skills from that source whose `owners` frontmatter contains that owner. |
| `org` | `<source-id>:<owner>` | Same matching behavior as `author`; the scope is a policy label. |

Local skills and skills from `trusted = true` sources are approved automatically. Non-interactive commands can use existing approvals but never create new approvals.

Prefer `dalo approve` for all approval changes. The TOML format remains
documented for auditability and recovery, but does not need to be edited for
normal approval workflows.

## `lock.toml`

Schema version: `schema_version = 1`.

This file is Dalo's resolved user lock. `sync` rewrites source snapshots, active skills, pending approvals, unlinked skills, and target materialization summaries. Instruction commands preserve and update active instruction-pack entries.

Top-level fields:

| Field | Meaning |
| --- | --- |
| `sources[]` | Source ID, kind, path, and optional commit. |
| `active_skills[]` | Skills that should be linked into targets. |
| `pending_approval_skills[]` | Skills blocked by approval. |
| `unlinked_skills[]` | Managed skills not linked, with a reason such as shadowing. |
| `target_materializations[]` | Last sync operations by target path. |
| `active_instruction_packs[]` | Instruction packs rendered into instruction files. |

Important record fields:

| Record | Fields |
| --- | --- |
| `LockedSource` | `id`, `kind`, `path`, optional `commit` |
| `LockedSkill` | `source_ref`, `slot_name`, optional `id`, `source_id`, `source_kind`, optional `reason` |
| `LockedTargetMaterialization` | `link_path`, optional `desired_path`, `kind`, `status`, optional `reason` |
| `LockedInstructionPack` | `pack_id`, `target`, `source_id`, optional `commit`, optional `version` |

## `state.toml`

Schema version: `schema_version = 1`.

This is internal state. Users normally inspect it through `target detect`, `status`, `sync`, and `resolve list`.

Top-level fields:

| Field | Meaning |
| --- | --- |
| `targets[]` | Logical target links with `id`, `path`, `canonical_path`, and `enabled`. |
| `materialization_dirs[]` | Canonical physical directories and the logical target IDs sharing each directory. |
| `owned_skills[]` | Symlinks Dalo owns: `target_id`, `slot_name`, `link_path`, `store_path`. |
| `protected_skills[]` | Unmanaged target slots kept by the user: `target_id`, `slot_name`. Legacy path-based entries migrate on read. |

Unknown fields in this internal state model are retained across reads and writes for downgrade safety after additive changes. Breaking changes still require a schema-version bump. User-authored configuration remains strict.

## `source-lock.toml`

Schema version: `schema_version = 3`.

This file stores catalog pins and inventory snapshots. It is written by catalog selection and read by drift checks.

Top-level fields:

| Field | Meaning |
| --- | --- |
| `catalogs[]` | One `CatalogLock` per pinned catalog source. |
| `catalogs[].source_id` | Catalog source ID. |
| `catalogs[].commit` | Pinned commit used for the inventory snapshot. |
| `catalogs[].selected[]` | Selected skill references. |
| `catalogs[].inventory[]` | Pinned catalog entries. |

Inventory entry fields:

| Field | Meaning |
| --- | --- |
| `id` | Optional stable skill ID from frontmatter. |
| `slot_name` | Install slot name. |
| `path` | Skill directory path relative to the catalog root. |
| `content_hash` | Hash over skill directory content, executable file bits, and symlink metadata. |
| `metadata_hash` | Hash over parsed skill metadata. |
| `requires[]` | Declared same-source dependencies. |

## `SKILL.md` Frontmatter

Dalo discovers a skill by finding a directory containing `SKILL.md`. If the file starts with YAML frontmatter fenced by `---` lines, Dalo reads these fields:

```markdown
---
id: review-helper
name: review-helper
description: Review pull requests for behavior regressions
owners:
  - platform-team
tags:
  - review
requires:
  - base-style
---

# Review Helper
```

| Field | Required | Meaning |
| --- | --- | --- |
| `id` | no | Stable skill identity. Use for catalog selections and source-qualified approvals. |
| `name` | no | Preferred slot name. Must be a safe slot name; otherwise Dalo falls back to the folder name and records an inventory warning. |
| `description` | no | Human-readable description shown in catalog inspection. |
| `owners[]` | no | Approval owner strings matched by `author` and `org` approvals. |
| `tags[]` | no | User metadata. |
| `requires[]` | no | Same-source or same-catalog dependencies. Required skills are expanded only when the closure is linkable and approved. |

If `name` is absent, the directory name is the slot name. Duplicate slot names within one source are warned and de-duplicated by resolver behavior.

## Instruction Packs

Instruction packs are Markdown files in `local/instructions/<id>.md` or
`<source>/instructions/<id>.md`. Dalo discovers both locations, but
`instructions enable` currently reads only local packs; source packs are
discovery-only. Pack IDs use the same safe token rule as source IDs: letters,
digits, `.`, `_`, and `-`, excluding `.` and `..`.

Dalo currently reads optional leading metadata lines from the first five lines:

```markdown
version: 1.0.0
topics: review, formatting

# Team Style

Use concise review comments.
```

`tags:` can be used instead of `topics:`. Topics are comma-separated and are used for advisory overlap warnings when multiple active packs share topics.

Managed blocks use these markers:

```markdown
<!-- dalo:start team-style -->
...
<!-- dalo:end team-style -->
```

Dalo only rewrites bytes inside the pack's own managed block. Content outside managed blocks is preserved.