docs(17): create phase plan for custom bind mounts

Phase 17: Custom Bind Mounts
- 3 plans in 3 waves
- Plan 01: Core mount module (parsing, validation, error types) and config schema
- Plan 02: CLI mount subcommand (add/remove/list) and start flags (--mount, --no-mounts)
- Plan 03: Container creation with bind mounts and status display

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: pRizz

.planning/ROADMAP.md

@@ -329,19 +329,19 @@ Plans:
 **Requirements**: None (enhancement)
 **Note**: Users often want to work with local project directories inside the container. This phase adds configuration and CLI options to specify bind mounts that map host paths to container paths.
 **Success Criteria** (what must be TRUE):
-  1. User can add bind mounts via `occ config set mounts "/path/on/host:/path/in/container"`
+  1. User can add bind mounts via `occ mount add /host/path:/container/path`
   2. User can add multiple mounts (array in config)
   3. Mounts are applied when container starts
   4. User can specify read-only mounts via `:ro` suffix
   5. Invalid paths (non-existent directories) are validated before container start
   6. `occ start --mount /path:/container/path` allows one-time mount without persisting to config
   7. `occ status` shows active bind mounts
-**Plans**: TBD
+**Plans**: 3 plans
 
 Plans:
-- [ ] 17-01: TBD (config schema for mounts, validation)
-- [ ] 17-02: TBD (container creation with bind mounts)
-- [ ] 17-03: TBD (CLI commands and status display)
+- [ ] 17-01-PLAN.md — Core mount module (parsing, validation, error types) and config schema extension
+- [ ] 17-02-PLAN.md — CLI mount subcommand (add/remove/list) and start command flags (--mount, --no-mounts)
+- [ ] 17-03-PLAN.md — Container creation with bind mounts and status display of active mounts
 
 ### Phase 18: CLI Sync Strategy
 **Goal**: Develop and implement a strategy to ensure the Rust CLI and Node CLI remain feature-complete and behavior-consistent
@@ -559,7 +559,7 @@ Phases execute in numeric order: 1 -> 2 -> 3 -> ... -> 22 -> 23 -> 24 -> 25 -> 2
 | 14. Versioning and Release Automation | 3/3 | ✓ Complete | 2026-01-23 |
 | 15. Prebuilt Image Option | 3/3 | ✓ Complete | 2026-01-24 |
 | 16. Code Quality Audit | 2/2 | ✓ Complete | 2026-01-25 |
-| 17. Custom Bind Mounts | 0/3 | Not started | - |
+| 17. Custom Bind Mounts | 0/3 | Planned | - |
 | 18. CLI Sync Strategy | 0/3 | Not started | - |
 | 19. CI/CD Automation | - | MERGED | - |
 | 20. One-Click Cloud Deploy | 0/3 | Not started | - |
@@ -574,4 +574,4 @@ Phases execute in numeric order: 1 -> 2 -> 3 -> ... -> 22 -> 23 -> 24 -> 25 -> 2
 
 ---
 *Roadmap created: 2026-01-18*
-*Last updated: 2026-01-25 (Phase 16 complete)*
+*Last updated: 2026-01-25 (Phase 17 planned)*

.planning/phases/17-custom-bind-mounts/17-01-PLAN.md

@@ -0,0 +1,191 @@
+---
+phase: 17-custom-bind-mounts
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - packages/core/src/config/schema.rs
+  - packages/core/src/docker/mount.rs
+  - packages/core/src/docker/mod.rs
+autonomous: true
+
+must_haves:
+  truths:
+    - "Mount string can be parsed into host path, container path, and read-only flag"
+    - "Invalid mount formats are rejected with clear error messages"
+    - "Relative paths are rejected with actionable error"
+    - "Non-existent paths are rejected with clear error"
+    - "Symlinks are resolved to their target directories"
+    - "Config stores mounts as array of strings"
+  artifacts:
+    - path: "packages/core/src/docker/mount.rs"
+      provides: "Mount parsing, validation, and Bollard conversion"
+      exports: ["ParsedMount", "MountError", "validate_mount_path", "check_container_path_warning"]
+    - path: "packages/core/src/config/schema.rs"
+      provides: "Config mounts field"
+      contains: "pub mounts: Vec<String>"
+  key_links:
+    - from: "packages/core/src/docker/mount.rs"
+      to: "bollard::service::Mount"
+      via: "to_bollard_mount() method"
+      pattern: "MountTypeEnum::BIND"
+---
+
+<objective>
+Create the core mount parsing and validation module with config schema extension.
+
+Purpose: Establish the foundation for bind mount support with proper validation before container integration.
+Output: `mount.rs` module with ParsedMount struct, MountError enum, validation functions, and config schema with `mounts: Vec<String>` field.
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/execute-plan.md
+@~/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+@.planning/phases/17-custom-bind-mounts/17-CONTEXT.md
+@.planning/phases/17-custom-bind-mounts/17-RESEARCH.md
+@packages/core/src/config/schema.rs
+@packages/core/src/docker/mod.rs
+@packages/core/src/docker/error.rs
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Create mount.rs module with parsing and validation</name>
+  <files>packages/core/src/docker/mount.rs, packages/core/src/docker/mod.rs</files>
+  <action>
+Create `packages/core/src/docker/mount.rs` with:
+
+1. **MountError enum** using thiserror:
+   - `RelativePath(String)` - "Mount paths must be absolute. Use: /full/path/to/dir"
+   - `InvalidFormat(String)` - "Invalid mount format. Expected: /host/path:/container/path[:ro]"
+   - `PathNotFound(String, String)` - path and underlying error
+   - `NotADirectory(String)` - "Path is not a directory"
+   - `PermissionDenied(String)` - "Cannot access path"
+
+2. **ParsedMount struct**:
+   ```rust
+   pub struct ParsedMount {
+       pub host_path: PathBuf,
+       pub container_path: String,
+       pub read_only: bool,
+   }
+   ```
+
+3. **ParsedMount::parse()** method:
+   - Split mount string by `:` (handle 2 or 3 parts)
+   - Part 1: host path (must be absolute)
+   - Part 2: container path
+   - Part 3 (optional): "ro" or "rw" (default rw)
+   - Return MountError::InvalidFormat for wrong number of parts
+   - Return MountError::RelativePath if host path not absolute
+
+4. **ParsedMount::to_bollard_mount()** method:
+   ```rust
+   pub fn to_bollard_mount(&self) -> bollard::service::Mount {
+       Mount {
+           target: Some(self.container_path.clone()),
+           source: Some(self.host_path.to_string_lossy().to_string()),
+           typ: Some(MountTypeEnum::BIND),
+           read_only: Some(self.read_only),
+           ..Default::default()
+       }
+   }
+   ```
+
+5. **validate_mount_path()** function:
+   - Check `is_absolute()` - return MountError::RelativePath
+   - Call `std::fs::canonicalize()` - return MountError::PathNotFound on error
+   - Call `std::fs::metadata()` - return MountError::PathNotFound or PermissionDenied
+   - Check `metadata.is_dir()` - return MountError::NotADirectory
+   - Return Ok(canonical_path)
+
+6. **check_container_path_warning()** function:
+   - SYSTEM_PATHS constant: `/etc`, `/usr`, `/bin`, `/sbin`, `/lib`, `/var`
+   - Return Some(warning_string) if container_path starts with any system path
+   - Return None otherwise
+
+7. **Unit tests**:
+   - `parse_valid_mount_rw` - "/a:/b" -> host=/a, container=/b, read_only=false
+   - `parse_valid_mount_ro` - "/a:/b:ro" -> read_only=true
+   - `parse_valid_mount_explicit_rw` - "/a:/b:rw" -> read_only=false
+   - `parse_invalid_format_single_part` - "invalid" -> InvalidFormat
+   - `parse_invalid_format_too_many_parts` - "/a:/b:ro:extra" -> InvalidFormat
+   - `parse_relative_path_rejected` - "./rel:/b" -> RelativePath
+   - `system_path_warning` - "/etc/passwd" triggers warning
+   - `non_system_path_no_warning` - "/workspace/data" no warning
+
+Update `packages/core/src/docker/mod.rs`:
+- Add `pub mod mount;`
+- Add `pub use mount::{MountError, ParsedMount, check_container_path_warning, validate_mount_path};`
+  </action>
+  <verify>
+Run `cargo build -p opencode-cloud-core` to verify compilation.
+Run `cargo test -p opencode-cloud-core mount::` to verify tests pass.
+  </verify>
+  <done>
+mount.rs exists with ParsedMount, MountError, validate_mount_path, check_container_path_warning. All unit tests pass. Module exported from docker/mod.rs.
+  </done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Add mounts field to config schema</name>
+  <files>packages/core/src/config/schema.rs</files>
+  <action>
+In `packages/core/src/config/schema.rs`:
+
+1. Add `mounts` field to Config struct after `update_check`:
+   ```rust
+   /// Bind mounts to apply when starting the container
+   /// Format: ["/host/path:/container/path", "/host:/mnt:ro"]
+   #[serde(default)]
+   pub mounts: Vec<String>,
+   ```
+
+2. Update `Default for Config` impl:
+   - Add `mounts: Vec::new(),` in the default initialization
+
+3. Add tests:
+   - `test_default_config_mounts_field` - default config has empty mounts vec
+   - `test_serialize_deserialize_with_mounts` - roundtrip with mounts array
+   - `test_mounts_field_default_on_missing` - old configs without mounts get empty vec
+
+Ensure existing tests still pass (the deny_unknown_fields attribute should not affect new fields we add).
+  </action>
+  <verify>
+Run `cargo test -p opencode-cloud-core config::` to verify all config tests pass.
+Run `cargo build -p opencode-cloud-core` to verify compilation.
+  </verify>
+  <done>
+Config struct has `mounts: Vec<String>` field with serde default. All existing and new config tests pass.
+  </done>
+</task>
+
+</tasks>
+
+<verification>
+1. `cargo build --all-targets --all-features` passes
+2. `cargo test --all-features` passes
+3. `cargo clippy --all-targets --all-features -- -D warnings` passes
+4. ParsedMount can parse "/host:/container", "/host:/container:ro", "/host:/container:rw"
+5. Validation rejects relative paths, non-existent paths, non-directories
+6. Config loads and saves with mounts array
+</verification>
+
+<success_criteria>
+- Mount parsing works for all valid formats (2-part rw, 3-part ro/rw)
+- Validation catches all error cases with clear messages
+- Config schema accepts mounts array and handles old configs gracefully
+- All tests pass, no clippy warnings
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/17-custom-bind-mounts/17-01-SUMMARY.md`
+</output>