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.
docs: document the universal --json output alias (#765)
Every command with --format text|json now also accepts --json (alias for
--format json; --json wins over --format text). Authoritative note + full
command list in Container Operations; inline shorthand on Image/Snapshot/
Health pages. Notes the coi container exec exception (--format json|raw).
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.
0.10.0 release sweep: convert removed flags/env-vars to config-key docs, add 0.9->0.10 migration section
PUSH TO MASTER ONLY WHEN v0.10.0 IS TAGGED — this describes 0.10 behavior.
- Migration-Guide: full 'Upgrading from 0.9 to 0.10' section (removed-flags
table, deleted env-var layers, claude-on-incus retirement, resume
persistence conversion, profile-beats-project-config, new opt-in features
incl. [[credentials]], hardened profile, use_sudo, ready_timeout, coi run
script, list filters)
- Configuration: hierarchy table drops the env-var and config-flag layers;
env-var section becomes a removed->replacement table; CLI flags section
rewritten around operational-only flags with a removed-flags table;
[shell] use_tmux added to the reference
- Getting-Started, Best-Practices, Architecture, Container-Lifecycle,
Container-Operations, Tmux-Automation: --persistent examples converted to
[container] persistent = true config; shutdown --timeout ->
shutdown_timeout
- Image-Management: --image/--persistent/--compression workflows converted
to config/profile equivalents (image publish keeps --compression)
- Supported-Tools: --tool selection converted to [tool] name / per-tool
profiles; new 'Tool Credentials and Third-Party Providers' section
covering the credential catalog and [[credentials]]
- Profiles: profile create flag list matches 0.10 (--inherits/--user/
--project only); profile-vs-project-config precedence note
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: quick-win formatting pass across all wiki pages
- Add H1 title to all 16 pages that were missing one
- Add FAQ question index with 22 anchor-linked entries grouped by category
- Add See Also section to all 19 pages with curated cross-links
- Upgrade three high-risk inline warnings to blockquote callouts:
allow_local_network_access, mount parent dir, disable_protection
docs: replace em dashes with hyphens across all wiki pages
docs: update image-not-found behaviour to reflect interactive build prompt
Document v0.8.1 features and fix minor v0.8.0 gaps
v0.8.1 features now documented:
- Profile auto-resume: --resume restores original profile (Container-Lifecycle)
- `close` command as safe alias for poweroff inside containers (Container-Lifecycle)
- Git identity guard: user.useConfigOnly=true prevents "code" commits (Security-Best-Practices)
- Auto-trust mise config files via MISE_TRUSTED_CONFIG_PATHS (Image-Management)
- Secure env-var forwarding via tmux -e, not shell export (Container-Lifecycle)
v0.8.0 minor fixes:
- Container-Operations: fix bare `coi` image name → `coi-default` in launch example
- Profiles: show built-in `default` profile row in `coi profile list` example output
- Security-Best-Practices: renumber summary list after git identity guard insertion
Fix outdated wiki: auto-build claim and missing re-login requirement
- Image-Management.md: Remove incorrect claim that `coi shell` and
`coi run` auto-build missing images. This was removed in v0.8.0 as
a breaking change — users must run `coi build` explicitly.
- Linux-Setup-Guide.md: Add prominent re-login/newgrp requirement after
`usermod -aG incus-admin` to all distro sections (Arch, Fedora,
openSUSE, Ubuntu). With the sg removal in v0.8.1, the incus-admin
group must be active in the user's session — previously sg handled
this transparently.
Fix final documentation issues for 0.8.0
- Image-Management: fix prose reference [build] → [container.build]
- Configuration: fix network.logging defaults (enabled=true, path=~/.coi/logs/network.log)
Fix remaining documentation inconsistencies for 0.8.0
- Image-Management: migrate profile example from deprecated [build] to [container.build]
- Configuration: remove "aider" from tool name comment (not yet registered),
move --tool from global flags to shell-only section
- Security-Monitoring: clarify write threshold mirrors read threshold (no separate config key)
- Profiles: add missing extended fields to Available Fields table
(model, paths, incus, git, ssh, security, monitoring, timezone, inherits)
Docs audit for 0.8.0: fix [defaults] → [container], coi resume → coi unfreeze, add security features
- Fix [defaults] → [container] for image/persistent in Configuration.md, Image-Management.md
- Replace all coi resume → coi unfreeze references (Security-Monitoring, Troubleshooting, Lifecycle)
- Add host-side immutable protection and guest API sections to Security-Best-Practices.md
- Add container aliases section to Container-Lifecycle-and-Sessions.md
- Update System-Health-Check.md for multi-pool support
- Add host_immutable, alias, storage_pool to config reference
Update wiki for 0.8.0 release
- Rename default image coi → coi-default
- Move config path ~/.config/coi/config.toml → ~/.coi/config.toml
- Drop /etc/coi/ and ~/.config/coi/ from config hierarchy
- Replace coi build custom with profile-based build workflow
- Rename coi profile show → coi profile info
- Document profile inheritance (inherits field)
- Document coi profile create/edit/delete commands
- Remove non-existent coi config --init reference
Document --compression flag and host timezone inheritance
- Image-Management: Add compression examples and dedicated section
- Configuration: Add [timezone] config section and --timezone CLI flag
Fix image delete documentation - remove non-existent --force flag
Add focused usage guides: Container Operations, File Transfer, Tmux Automation, Image Management