ngn-agent/.planning/phases/06-default-repos-ssh-mount/06-CONTEXT.md

# Phase 6: Default Repos & SSH Mount - Context

**Gathered:** 2026-06-14
**Status:** Ready for planning

<domain>
## Phase Boundary

Enable automatic availability of DEFAULT_REPOS in every new Hermes session and provide on-demand repo cloning capability. Repos are mounted directly from host filesystem (not cloned inside Docker) to preserve git worktrees and avoid redundant clones.

**In scope:** SSH key mounting for git auth, repo volume mounts for 3 default repos, shell init script for session workspace setup, DEFAULT_REPOS configurability, on-demand cloning for additional repos

**Out of scope:** Hindsight memory integration (Phase 5 already done), session lifecycle skill (Phase 7), cron reporting (Phase 8), migration of existing session data
</domain>

<decisions>
## Implementation Decisions

### Git Auth Strategy
- **D-01:** Mount specific SSH keys read-only into Docker — `~/.ssh/id_ed25519razer` and `~/.ssh/id_rsa` plus `~/.ssh/config`
  - Config: Add to `terminal.docker_volumes` in `~/.hermes/config.yaml`
  - `~/.ssh/id_ed25519razer:/root/.ssh/id_ed25519razer:ro`
  - `~/.ssh/id_rsa:/root/.ssh/id_rsa:ro`
  - `~/.ssh/config:/root/.ssh/config:ro`
  - The existing `~/.ssh/config` already maps `bitbucket.org` → `id_ed25519razer`

### Repo Workspace Mounts
- **D-02:** Mount repo directories directly from host filesystem — repos live at `~/Razer/<repo>` and are mounted into Docker as host-mounted volumes
  - Config: Add to `terminal.docker_volumes`:
  - `~/Razer/rai-ops:/workspace/rai-ops:rw`
  - `~/Razer/rai-deployment:/workspace/rai-deployment:rw`
  - `~/Razer/rai-devtools:/workspace/rai-devtools:rw`
  - This preserves existing git worktrees, branches, and avoids re-cloning
  - Container has read-write access for git operations

### Session Init Script
- **D-03:** Create `session-init.sh` in `~/.hermes/scripts/` (already mounted to `/usr/local/bin:ro`). Script checks that DEFAULT_REPOS are mounted at expected paths and logs status
  - Config: Add to `terminal.shell_init_files`: `["/usr/local/bin/session-init.sh"]`
  - Behavior: check each repo in DEFAULT_REPOS exists at `/workspace/<name>`, log status, skip if absent (no blocking)

### DEFAULT_REPOS Configurability
- **D-04:** `DEFAULT_REPOS` defined as an env var in `~/.hermes/.env`:
  - `DEFAULT_REPOS=rai-ops,rai-deployment,rai-devtools`
  - Forwarded into Docker via `docker_forward_env`
  - The session init script reads this env var to validate mounts
  - User can add/remove repos by editing .env + adding/removing volume mounts

### On-Demand Repo Cloning (REPO-02)
- **D-05:** Agent clones additional repos into `/workspace/` using `git clone` inside Docker. SSH keys are mounted so auth works for any Bitbucket repo the user has access to
  - Clones are ephemeral (lost on container restart) — suitable for temporary work
  - Agent uses `git clone git@bitbucket.org:razersw/<repo>.git`
  - No dedicated skill needed — git is available in the Docker image

### the agent's Discretion
- **Init script error handling**: The script should exit gracefully if a repo is missing (non-blocking — session should still start)
- **On-demand clone destination**: Default to `/workspace/` unless user specifies otherwise
</decisions>

<canonical_refs>
## Canonical References

**Downstream agents MUST read these before planning or implementing.**

### Existing Hermes Configuration
- `~/.hermes/config.yaml` §`terminal.docker_volumes` — Current volume mounts (SSO cache, scripts) — the planner must append to this list
- `~/.hermes/config.yaml` §`terminal.shell_init_files` — Currently empty, needs `session-init.sh`
- `~/.hermes/config.yaml` §`terminal.docker_forward_env` — Currently forwards JIRA_EMAIL and JIRA_API_TOKEN
- `~/.hermes/scripts/` — Existing scripts directory (ngn-jira, ngn-confluence, ngn-bitbucket) — session-init.sh goes here
- `~/.hermes/.env` — Existing env vars (OPENROUTER_API_KEY, TELEGRAM_BOT_TOKEN, JIRA_API_TOKEN, etc.)

### SSH Configuration
- `~/.ssh/config` — Maps bitbucket.org → `id_ed25519razer`
- `~/.ssh/id_ed25519razer` — Razer-specific SSH key
- `~/.ssh/id_rsa` — RSA key

### Project Documents
- `.planning/REQUIREMENTS.md` §REPO-01, REPO-02 — Requirement definitions
- `.planning/ROADMAP.md` §Phase 6 — Phase goal and success criteria
- `.planning/research/SUMMARY.md` §Phase 2 — Research on repo mounting vs cloning, credential strategies
- `.planning/research/PITFALLS.md` — Git clone failures in Docker, SSH credential exposure risks
</canonical_refs>

<code_context>
## Existing Code Insights

### Reusable Assets
- **`~/.hermes/scripts/` mount**: Already mounted to `/usr/local/bin:ro` — new `session-init.sh` goes here automatically
- **Docker volumes pattern**: Existing mount entries in config.yaml show the pattern (`host:container:mode`)

### Established Patterns
- **Read-only sensitive files**: `.aws/config` mounted `:ro` — SSH keys follow the same pattern for security
- **Scripts mounted to /usr/local/bin**: `ngn-*` scripts already use this pattern — session-init.sh follows it

### Integration Points
- `~/.hermes/config.yaml` §`terminal.docker_volumes` — Append SSH key + repo mounts
- `~/.hermes/config.yaml` §`terminal.shell_init_files` — Set to `["/usr/local/bin/session-init.sh"]`
- `~/.hermes/config.yaml` §`terminal.docker_forward_env` — Append `DEFAULT_REPOS`
- `~/.hermes/.env` — Add `DEFAULT_REPOS=rai-ops,rai-deployment,rai-devtools`
- `~/.hermes/scripts/session-init.sh` — New file (create)
</code_context>

<specifics>
## Specific Ideas

- Mount repos read-write (`:rw`) so git operations inside container (branch, commit, push) work seamlessly — this is the core advantage over cloning
- The session-init.sh should be lightweight: just verify mounts exist and log status. Do NOT attempt git operations — the repos are already on disk with active worktrees
</specifics>

<deferred>
## Deferred Ideas

- Auto-register repos as git worktrees via Hermes' `worktree: true` config — already handled by the host-side git setup
- Per-repo deploy keys instead of personal SSH key — future security hardening
</deferred>

---

*Phase: 6-Default Repos & SSH Mount*
*Context gathered: 2026-06-14*