docs: align wiki to the Karafka writing style
Style-only pass across 39 pages: reduce decorative bold to scannable labels and
callouts, Title Case headings, expand contractions, present tense, US English,
cut filler and --- separators, tag code fences. Commands, code, config,
COI_* env vars, paths, URLs, wiki links/anchors, and tables left unchanged.
docs: rebrand to Coi (drop all-caps COI; Coi primary, coi command)
COI -> Coi across all pages; sidebar + Home first-mention use "Coi (Code on Incus)".
Preserved: COI_* env-var names and the literal "# COI Sandbox ..." context markers
(they document the actual on-disk marker text). Lowercase coi commands unchanged.
docs: dedicated Updating COI page (binary + detection databases)
Promote update docs out of System-Health-Check into a standalone
Updating-COI page so it is discoverable on its own (prompted by #821).
- Document coi update / update core / update patterns, including the
GTFOBins + Sigma detection-database refresh the old docs omitted.
- Add troubleshooting for the Sigma/GTFOBins git pull --ff-only failure
(remove the clone dir and re-run) and the v0.11.0 doubled-version bug.
- Self-Update and System-Health-Check#updating-coi now point to the new
page; update Home, Sidebar, and Image-Management links.
Add 'Threat model: containment limits' page (kernel hardening flags + freshness guidance)
docs(home): name the current tool set in the intro (Codex, pi, omp)
docs: add 0.11 → 0.12 Migration Guide entry
The Migration Guide stopped at 0.10.1 → 0.11.0; add the 0.11 → 0.12 section for
the upcoming release. 0.12.0 is additive (no breaking changes, no config
migration), so it follows the "New in X (opt-in, no action needed)" pattern:
lists the new capabilities (coi tool spec, coi top, codex, omp,
SANDBOX_CONTEXT.json, egress hardening, git readonly) with links to their pages,
plus Notes on the three fixes with upgrade-relevant behavior (#744 tool env on
exec/reused containers, #733 tmpfs_size, #726 shell storage_pool).
Surfaced the new entry in Home + _Sidebar migration sub-links. All links verified.
docs: split Supported Tools — extract Sandbox Context + Adding New Tools
Supported-Tools.md mixed three audiences. Keep all per-tool sections together
(users compare tools at a glance) and extract the two genuinely independent,
cross-cutting sections into their own pages (page now ~11.5 KB / 272 lines,
down from ~15.6 KB / 379 lines):
- New **Sandbox Context** — the `~/SANDBOX_CONTEXT.md` / `.json` environment
description, auto-context injection per tool, disabling it, and custom/JSON
context files. It's referenced from Architecture and Configuration and isn't
really about *which* tool.
- New **Adding New Tools** — contributor docs: the `Tool` interface and optional
capability interfaces (incl. ToolWithPrompt / ToolWithContainerEnv for
`coi tool spec`) with worked examples.
Supported-Tools keeps pointer stubs to both. Re-pointed the Configuration
cross-reference to the new Sandbox Context page; credentials/permission-mode
links stay valid (those sections remain). Added both pages to Home + _Sidebar
(nested under Supported Tools). All internal links verified.
docs: split Network Isolation into focused pages
Network-Isolation.md had grown to ~20 KB / 365 lines covering four distinct
topics. Extract the two self-contained ones into their own pages, leaving the
core page focused on egress modes + hardening (now ~13.7 KB / 244 lines):
- New **Static Host Entries** — `[[network.hosts]]` config, per-host `ports`,
the per-mode reachability table, trusted-scope rules, and runtime `coi hosts`.
- New **nftables Setup** — the open-mode workaround, install + sudoers steps,
how the FORWARD-chain rules work, and orphaned-rule cleanup.
Network-Isolation keeps short pointer stubs to both; the "(see below)" per-host
ports reference now links the new page. Host Access to Container Services stays
on the core page (it's `allow_local_network_access` firewall content, not
port-publishing). Re-pointed the Container-Operations and Configuration
cross-references to Static Host Entries, and added both pages to Home + _Sidebar
(nested under Network Isolation). All internal links verified.
docs: cover 0.12.0 capabilities (coi tool spec, coi top, omp, SANDBOX_CONTEXT.json)
Bring the wiki up to date with capabilities added since the last update:
- New page **Headless Orchestration (`coi tool spec`)** — the non-executing
launch-spec API for external orchestrators, incl. --continue / --resume-id /
--resume, the `prompt` field for non-embedding tools, and env/secrets model.
- New page **Resource Usage (`coi top`)** — live per-container/per-process CPU,
memory, disk and network usage; flags, examples, and how it reads cgroups.
- **Supported Tools**: add the omp (Oh My Pi) tool section; document the
~/SANDBOX_CONTEXT.json companion (context_json / context_json_file, trusted
scope only).
- **Configuration**: add context_json / context_json_file to the [tool] reference.
- Wire both new pages into Home + _Sidebar; cross-link Tmux Automation ->
Headless Orchestration.
(codex, tmpfs_size, per-host/per-destination ports, dns_servers, allowed_ports,
and git readonly were already documented.)
Align wiki with 0.11.1: OrbStack guide, filesystem-first UID mapping, dir-pool health warning, idempotent context injection, version-fix note
- macOS Setup Guide: OrbStack is now a first-class documented option
(setup steps, how COI handles the FUSE-backed macOS share via
raw.idmap, the OrbStack >=2.2.2 silent-breakage background, storage
notes); 'How It Works' rewritten around the v0.11.1 filesystem check
with the reactive fallback; Manual Override reframed as rarely
needed; Colima instructions now install Incus from Zabbly (Ubuntu's
6.0 is below the required 6.1).
- Configuration/Architecture/File-Transfer/FAQ pages: UID-mapping
mechanism descriptions updated (auto-selected shift vs raw.idmap),
disable_shift comment rewritten, Colima-only framing widened to
Colima/Lima/OrbStack.
- System Health Check/Troubleshooting/Best Practices/Getting Started/
Linux Setup Guide: dir-pool driver warning documented (detection,
cost, fix), example output shows the new 'pool (driver)' label,
manual-setup example no longer recommends a dir pool, Zabbly note
reframed around the automatic raw.idmap recovery, #673 version/update
known-issue note added.
- Troubleshooting/Supported-Tools/Profiles: idempotent marker-delimited
sandbox-context injection documented incl. auto-healing of bloated
files; tool interface snippets synced (AlwaysSetupConfig, full effort
level list).
- nftables internals: NFT monitoring is disabled by default.
- Nav (Home/Sidebar/Footer): 0.10.1->0.11.0 migration links; FAQ count
fix; IPv6 host-side blocking wording.
Document [ports] host port publishing (v0.10.1, #558)
New Port Publishing page: pool + map forms, deterministic allocation,
preflight, coi list display, env vars, trust gating, persistent-container
reuse semantics, troubleshooting. Wired into the sidebar, Home, the
Configuration section table + full config reference, and cross-referenced
from Network Isolation (proxy devices don't touch the nft rules).
Post-release audit: fix ~50 inaccuracies vs v0.10.0 behavior
Triple-check audit of every page against the released binary and code.
Systemic: firewalld -> nftables (stale since the v0.9 #405 migration) across
Network-Isolation, Linux-Setup-Guide, Architecture-and-Security-Model,
Getting-Started, Home, FAQ*, Best-Practices, Troubleshooting,
System-Health-Check — including the whole 'Firewalld Setup' section that
told users to create the wrong sudoers file (/etc/sudoers.d/coi-firewalld);
now documents nftables + /etc/sudoers.d/coi-nft (matching install.sh), the
real error string, use_sudo=false, and the real orphan classes and health
check names. Distro-default-firewall tips (Fedora/openSUSE) kept but
decoupled from COI's own mechanism.
Audit-Log: JSONL examples and field reference rewritten to the real
ThreatEvent shape (id/timestamp/level/category/title/description/evidence/
action — the old examples used fields that never existed); COI_AUDIT_*
tuning corrected (host env is not forwarded; use incus config set).
Security-Best-Practices: default protected-paths table matches the 0.10
set; protection-weakening keys documented as trusted-scope only (untrusted
project configs are sanitized); #533 linked-worktree support and #556 git
identity seeding documented.
Command usage: coi update core --check (not coi update --check), coi info
<session-id>, coi persist <container>, coi run's interactive build prompt,
stop-before-publish in the image workflow, --slot pinning.
Config accuracy: memory enforce default is soft; effort_level accepts
low/medium/high/xhigh/max/auto (default unset); [limits.disk] values are
I/O rates not storage caps (Best-Practices example fixed); protected_paths
default list completed; threat levels are INFO/WARNING/HIGH/CRITICAL.
Navigation: 0.9->0.10 migration section linked from Home, sidebar, and
footer; broken FAQ prompt-injection anchor retargeted.
docs(wiki): extract audit log + coi audit into dedicated Audit-Log page
Security-Monitoring was the largest page (~500 lines). Move the on-disk audit
log format, field reference, and the full 'coi audit' command docs into a new
Audit-Log page (Security-Monitoring now links to it with a short stub). Retarget
inbound links (Session-Logs, Migration-Guide, Home, sidebar). Security-Monitoring
328 lines; all internal links verified.
docs(wiki): add persistent sidebar + footer nav; link Self-Update from Home
Health pass (post-0.9): wiki is otherwise healthy — no broken internal links,
no stale version/config references, page sizes reasonable. Add Karafka-style
persistent navigation (_Sidebar.md grouped by category, _Footer.md quick links)
and fix the orphaned Self-Update page (was a real page not linked from Home).
docs: 0.9 updates — upgrade guide (0.8→0.9), sockets, env_commands, pi
- Migration-Guide: add 'Upgrading from 0.8 to 0.9' (trust gate, network
sanitize, read-only .coi, protected git paths, allowlist/IPv6 tightening;
new features: sockets, env_commands, coi trust/audit, pi)
- Configuration: document [[sockets]] and [defaults.env_commands]; fix default
protected_paths list; add pi to tool name
- Supported-Tools: add pi section
- Home: link the 0.8→0.9 upgrade guide
docs: add coi audit and coi logs documentation
- Security-Monitoring.md: add full 'coi audit' section covering both
dump and follow modes, event format/types, all five event sources,
heartbeat liveness detection, jq filtering examples, agent tuning
env vars, and resource overhead
- Session-Logs.md: new page documenting 'coi logs', log file locations,
follow mode, output format, and the network-refresh background log
- Home.md: link to Session-Logs from the Security nav section; update
Security-Monitoring description to mention coi audit
Closes #390
docs: fix bugs and fill content gaps from re-analysis
Bug fixes:
- Linux-Setup-Guide: fix usermod command (incus,incus-admin not
'incus incus-admin $USER' which passed incus-admin as a username)
- Image-Management: clarify Best Practices item 4 — coi image publish
captures filesystem state, not process memory; stateful = snapshots only
Content improvements:
- Home.md: add one-sentence description of what COI is before the callout
- Tmux-Automation: replace non-deterministic sleep-based CI examples with
polling helpers; add Note callout explaining why fixed sleeps are unreliable
- FAQ.md: expand Troubleshooting Quick Links from 2 to 7 entries covering
container pause/kill, privileged=true error, Docker Compose, DNS build issues
- Resource-and-Time-Limits: add prose section explaining what each limit
actually does (CPU enforce/priority, memory hard vs soft, swap semantics,
disk I/O cgroup blkio, tmpfs, runtime auto-stop)
- File-Transfer: add UID shifting note explaining automatic ownership mapping
and when to chown after pushing to system paths
- Security-Monitoring: clarify [monitoring] vs [monitoring.nft] as two
independent subsystems with separate prerequisites
- Configuration: note that forward_env is top-level in profiles vs under
[defaults] in main config
- Migration-Guide: add 4 more entries from Troubleshooting content (bool
pointer fix, settings.json deep merge, Docker Compose three-step launch,
EXDEV session save fix, UID/GID remapping)
docs: complete structural, content, and style improvements (S4-S6, C1-C5, F5)
Structural:
- S4: Add Slot System section to Container-Lifecycle-and-Sessions explaining
container naming, auto-allocation, per-slot isolation, and alias suffixes
- S5: Merge Self-Update into System-Health-Check (update commands, how-it-works,
post-update steps); Self-Update.md becomes a redirect
- S6: Add Migration-Guide.md covering .coi.toml → .coi/config.toml move and
[[mounts]] vs [[mounts.default]] syntax difference
Content:
- C1: Add Best-Practices.md covering session mode selection, network mode
guide, monitoring recommendations, long-running tasks, team workflows,
AI-generated code handling, and storage cleanup
- C2: Expand Snapshot-Management.md with context opener (stateless vs stateful
tradeoffs, restore requirement) and Best Practices section
- C3: Add Troubleshooting section to Image-Management.md (image not found,
build failures, wrong image applied, stale image after update) and
Best Practices section
- C4: Document coi run in Container-Operations.md with use cases, flags,
and differences from coi shell
- C5: Add JSONL field schema tables to Security-Monitoring.md (common fields,
type-specific fields, NFT-specific fields)
Formatting:
- F5: Add Best Practices sections to Network-Isolation, Profiles,
Image-Management, and Snapshot-Management
Navigation:
- Home.md updated with Best-Practices and Migration-Guide in nav
docs: add Architecture, Getting-Started, and split FAQ into categories
- Add Architecture-and-Security-Model.md — conceptual "why COI" page
covering the threat model, all defense layers, architecture diagram,
and what COI does/does not protect against
- Add Getting-Started.md — step-by-step first-session walkthrough
covering install, coi build, coi shell, resume, parallel sessions,
and persistent mode, with links to next steps
- Split FAQ.md into three category files:
- FAQ-Platform-Comparisons.md (6 questions + comparison table)
- FAQ-Security-and-Trust.md (5 questions)
- FAQ-Setup-and-Operation.md (9 questions)
- Rewrite FAQ.md as a pure index with category table + troubleshooting
quick links
- Update Home.md: new Getting-Started and Architecture nav section,
point new-user callout to Getting-Started, list FAQ category pages
Add Linux Setup Guide for non-Ubuntu distros
New wiki page covering Arch/CachyOS, Fedora/RHEL, openSUSE, and Ubuntu
setup including Incus installation, idmap configuration, firewalld setup,
and common troubleshooting.
Addresses #317 (Arch Linux setup documentation).
Reduce documentation duplication and improve structure
- Deduplicate Sandbox Context: Configuration.md now links to Supported-Tools.md
instead of repeating the full auto-context section
- Move mount how-to from FAQ to Configuration.md "Mounting Additional Files" section;
FAQ entry replaced with short pointer
- Add "Getting Started" callout to Home.md for new users
- Trim Configuration.md Profiles section to a pointer (was duplicating Profiles.md)
Add Profiles wiki page, update Configuration and Home
- New Profiles.md page covering directory structure, config reference,
context files, build scripts, commands, and examples
- Update Configuration.md: replace outdated inline profiles section
with link to new page, update config reference
- Update Home.md: add Profiles link to navigation
docs: add Configuration page and document 0.8.0 features across wiki
- Create Configuration.md with full config reference (was linked but missing)
- Add SSH agent forwarding and env var forwarding to Container-Lifecycle-and-Sessions
- Update Network-Isolation with TTL-aware DNS refresh behavior
- Add sandbox context file docs to Supported-Tools
- Add SSH/env forwarding security considerations to Security-Best-Practices
- Fix stale mount_claude_config reference in FAQ
- Update env var isolation statement in FAQ for forward_env
- Add Configuration link to Home page
docs: add Configuration wiki page with hierarchy, per-repo config, and full reference
docs: add Security Monitoring and Supported Tools pages, update health checks
- Add Security-Monitoring.md: real-time threat detection, nftables monitoring,
automated response, audit logging
- Add Supported-Tools.md: Claude Code vs opencode comparison, tool selection,
API key configuration, adding new tools
- Update System-Health-Check.md: add Incus storage pool, monitoring checks,
container networking checks
- Update Security-Best-Practices.md: reference new Security Monitoring page
- Update Home.md: add links to new pages
Update Security Best Practices with automatic path protection feature
- Document automatic read-only mounting of security-sensitive paths
- Add table of default protected paths (.git/hooks, .git/config, .husky, .vscode)
- Document configuration options (additional_protected_paths, protected_paths, disable_protection)
- Explain attack vectors COI protects against
- Add symlink security section
- Reorganize Home.md with dedicated Security section
Add Container Operations, File Transfer, Tmux Automation, and Image Management to Home page
Add Snapshot Management to Home page
Add Container Lifecycle and Sessions to Home page