docs: ADR 0001-0003 — OpenCode commands, config merge, permissions default

Why: Architectural decisions recorded during planning phase.
See docs/plans/feature_opencode-commands_as_md_and_config_merge.md for full context.

docs/decisions/0001-opencode-command-output-format.md

@@ -0,0 +1,21 @@
+# ADR 0001: OpenCode commands written as .md files, not in opencode.json
+
+## Status
+Accepted
+
+## Date
+2026-02-20
+
+## Context
+OpenCode supports two equivalent formats for custom commands. Writing to opencode.json requires overwriting or merging the user's config file. Writing .md files is additive and non-destructive.
+
+## Decision
+The OpenCode target always emits commands as individual .md files in the commands/ subdirectory. The command key is never written to opencode.json by this tool.
+
+## Consequences
+- Positive: Installs are non-destructive. Commands are visible as individual files, easy to inspect. Consistent with agents/skills handling.
+- Negative: Users inspecting opencode.json won't see plugin commands; they must look in commands/.
+- Neutral: Requires OpenCode >= the version with command file support (confirmed stable).
+
+## Plan Reference
+Originated from: docs/plans/feature_opencode-commands_as_md_and_config_merge.md

docs/decisions/0002-opencode-json-merge-strategy.md

@@ -0,0 +1,21 @@
+# ADR 0002: Plugin merges into existing opencode.json rather than replacing it
+
+## Status
+Accepted
+
+## Date
+2026-02-20
+
+## Context
+Users have existing opencode.json files with personal configuration. The install command previously backed up and replaced this file entirely, destroying user settings.
+
+## Decision
+writeOpenCodeBundle reads existing opencode.json (if present), deep-merges plugin-provided keys without overwriting user-set values, and writes the merged result. User keys always win on conflict.
+
+## Consequences
+- Positive: User config preserved across installs. Re-installs are idempotent for user-set values.
+- Negative: Plugin cannot remove or update an MCP server entry if the user already has one with the same name.
+- Neutral: Backup of pre-merge file is still created for safety.
+
+## Plan Reference
+Originated from: docs/plans/feature_opencode-commands_as_md_and_config_merge.md

docs/decisions/0003-opencode-permissions-default-none.md

@@ -0,0 +1,21 @@
+# ADR 0003: Global permissions not written to opencode.json by default
+
+## Status
+Accepted
+
+## Date
+2026-02-20
+
+## Context
+Claude commands carry allowedTools as per-command restrictions. OpenCode has no per-command permission mechanism. Writing per-command restrictions as global permissions is semantically incorrect and pollutes the user's global config.
+
+## Decision
+--permissions defaults to "none". The plugin never writes permission or tools to opencode.json unless the user explicitly passes --permissions broad or --permissions from-command.
+
+## Consequences
+- Positive: User's global OpenCode permissions are never silently modified.
+- Negative: Users who relied on auto-set permissions must now pass the flag explicitly.
+- Neutral: The "broad" and "from-command" modes still work as documented for opt-in use.
+
+## Plan Reference
+Originated from: docs/plans/feature_opencode-commands_as_md_and_config_merge.md

docs/reports/index.md

@@ -0,0 +1,3 @@
+| Date | Run Directory | Plan Source | Summary |
+|------|--------------|-------------|---------|
+| 2026-02-20 | `opencode-commands-md-merge/` | `docs/plans/feature_opencode-commands_as_md_and_config_merge.md` | Implement OpenCode commands as .md files, deep-merge opencode.json, and change --permissions default to none |