docs: correct auth and network guidance after devcontainer change

The previous commit dropped the features block, --network=host and the
~/.ssh and ~/.config/gh mounts from .devcontainer/devcontainer.json, which
left four places in the repo describing a container that no longer exists.

.devcontainer/claude-code/README.md led with "Why --network=host is
Required" and an example devcontainer.json carrying runArgs and a features
block. The default path is now the one the template ships: authenticate
claude on the host, and the ~/.claude bind mount plus CLAUDE_CONFIG_DIR
hand those credentials to every container, so no OAuth flow runs inside
one. The OAuth callback explanation stays, reframed as the reason to opt
into host networking, along with what that costs -- VS Code extensions
stop installing (vscode-remote-release#9212), and every port the container
binds becomes a host port, so two branch containers collide. The example
now shows the feature declared in .devcontainer/ci/devcontainer.json, where
the image is built, and a launch config with neither features nor runArgs.

.devcontainer/claude-code/TROUBLESHOOTING.md repeated "add --network=host"
as the fix in its quick-reference config, in Issue 2 and in the setup
checklist, and told readers NetworkMode should read "host". Each now points
at host authentication first and names host networking as the opt-in with
its costs.

AGENTS.md claimed gh authentication is shared through a mounted
~/.config/gh. That mount is gone, and it never worked anyway: gh keeps its
token in the system keyring, so the mounted hosts.yml carried no
oauth_token. GitHub auth arrives as GH_TOKEN, which dl forwards into every
workspace it starts. A container opened by anything else -- devpod up, or
VS Code's Reopen in Container -- has no gh login until you export it.

.devcontainer/Dockerfile created /home/vscode/.ssh and
/home/vscode/.config/gh solely to receive the two deleted mounts. Both
blocks are removed.

Author: blooop

.devcontainer/Dockerfile

@@ -14,9 +14,3 @@ RUN echo 'eval "$(pixi completion -s bash)"' >> /home/vscode/.bashrc \
     && echo 'export PATH="$HOME/.pixi/bin:$PATH"' >> /home/vscode/.profile \
     && echo '# Workaround: pixi trampoline fails for bash scripts, so add env bin directly' >> /home/vscode/.profile \
     && echo '[ -d "$HOME/.pixi/envs/claude-shim/bin" ] && export PATH="$HOME/.pixi/envs/claude-shim/bin:$PATH"' >> /home/vscode/.profile
-
-# Create .ssh directory with proper permissions for SSH config mounts
-RUN mkdir -p /home/vscode/.ssh && chmod 700 /home/vscode/.ssh
-
-# Create .config/gh directory for GitHub CLI config mounts
-RUN mkdir -p /home/vscode/.config/gh

.devcontainer/claude-code/README.md

@@ -52,45 +52,58 @@ These files **must be writable** to enable:
 
 ### Setup
 
-Add this feature to your `devcontainer.json`:
+The feature is declared where the image is built, in `.devcontainer/ci/devcontainer.json`:
 
 ```json
 {
+  "build": {
+    "dockerfile": "../Dockerfile",
+    "context": "."
+  },
   "features": {
-    "./claude-code": {}
+    "../claude-code": {}
+  }
+}
+```
+
+CI publishes that image, and the `devcontainer.json` every branch launches from pulls it and declares neither `features` nor `runArgs`:
+
+```json
+{
+  "image": "ghcr.io/blooop/python_template/devcontainer:latest",
+  "containerEnv": {
+    "CLAUDE_CONFIG_DIR": "/home/vscode/.claude"
   },
-  "runArgs": ["--network=host"]
+  "mounts": [
+    "source=${localEnv:HOME}/.claude,target=/home/vscode/.claude,type=bind"
+  ]
 }
 ```
 
+Declaring the feature a second time there makes the devcontainer spec build a derived image on the first launch of every branch, reinstalling what the pulled image already carries.
+
 **Note**: Node.js is automatically installed via the `installsAfter` dependency mechanism - you don't need to explicitly add it to your features.
 
-### Why `--network=host` is Required
+### Authentication Uses Host Credentials, Not Host Networking
 
-The `runArgs: ["--network=host"]` is **critical for OAuth authentication** to work in containers.
+No OAuth flow runs inside the container. You authenticate `claude` once on the host, and the `~/.claude` bind mount plus `CLAUDE_CONFIG_DIR=/home/vscode/.claude` point the container at those same credentials, refresh tokens included. Every container of every branch reads them, and nothing has to reach the host's network to do it.
 
-**How OAuth works:**
-1. You run `claude` → starts OAuth flow
-2. Opens browser → you click "Authorize"
-3. Browser redirects to `http://localhost:<random-port>/callback`
-4. OAuth server running in container receives the callback
+### Why You Might Opt Into `--network=host`
 
-**The problem without host networking:**
-- OAuth server runs on port X **inside container**
-- Browser callback goes to port X on **host's localhost**
-- ❌ Container's port is not accessible from host → **callback fails**
+The one thing the bind mount does not give you is the interactive OAuth login *from inside* the container, which needs host networking to complete:
 
-**The solution:**
-- With `--network=host`, container shares host's network namespace
-- OAuth server on port X in container = port X on host
-- ✅ Browser callback reaches the container → **authentication succeeds**
+1. You run `claude` → it starts a callback server on a random port in the container
+2. Your browser opens the authorize page, you click "Authorize", and it redirects to `http://localhost:<that-port>/callback`
+3. On the default bridge network that port belongs to the container, not the host, so the browser cannot reach it and the CLI sits at "Paste code here"
 
-**Security note:** Host networking gives the container full network access. Only use in trusted environments.
+With `--network=host` the container shares the host's network namespace, port X in the container *is* port X on the host, and the callback lands.
 
-**Alternative (if host networking is not acceptable):**
-- Authenticate Claude on your host machine first
-- Credentials in `~/.claude/.credentials.json` are automatically shared with container
-- No OAuth flow needed in container
+Two costs come with it, and they are why this template does not set it:
+
+- **VS Code extensions stop installing**: [vscode-remote-release#9212](https://github.com/microsoft/vscode-remote-release/issues/9212), covered again under Troubleshooting below.
+- **Every port the container binds becomes a host port.** A container per branch is the reason these repos are launched with `dl`, and two branch containers on the host's network namespace collide on the first port they share.
+
+Host networking also gives the container full access to the host's network, so only use it in environments you trust.
 
 ### Build the Container
 
@@ -377,23 +390,15 @@ Then use both:
 
 **Problem**: Browser clicks "Authorize" but container never receives the callback.
 
-**Solution**: Add `--network=host` to your `devcontainer.json`:
-
-```json
-{
-  "runArgs": ["--network=host"]
-}
-```
-
-See "Why `--network=host` is Required" section above for details.
+**Solution**: Run `claude` on the host instead and let the container read the credentials it writes to `~/.claude`. If you need the login to happen inside the container, add `--network=host` and accept its costs -- see "Why You Might Opt Into `--network=host`" above.
 
 ### Interactive `claude` asks for authentication but `claude --print` works
 
 **Problem**: You're authenticated (credentials mounted) but interactive mode prompts for login.
 
-**Root cause**: Without `--network=host`, OAuth callbacks can't reach the container.
+**Root cause**: Interactive mode tried to start an OAuth flow, which means it found no usable credentials under `CLAUDE_CONFIG_DIR`.
 
-**Solution**: Add `"runArgs": ["--network=host"]` to devcontainer.json.
+**Solution**: Authenticate on the host so `~/.claude/.credentials.json` holds a live token, and check that `~/.claude` is actually mounted and `CLAUDE_CONFIG_DIR` points at it.
 
 ### VS Code extensions don't install with `--network=host`
 

.devcontainer/claude-code/TROUBLESHOOTING.md

@@ -19,20 +19,21 @@
 
 ```json
 {
-  "features": {
-    "ghcr.io/devcontainers/features/node:1": {},
-    "./claude-code": {}
-  },
-  "runArgs": ["--network=host"],
+  "image": "ghcr.io/blooop/python_template/devcontainer:latest",
   "containerEnv": {
     "CLAUDE_CONFIG_DIR": "/home/vscode/.claude",
     "XDG_CONFIG_HOME": "/home/vscode/.config",
     "XDG_CACHE_HOME": "/home/vscode/.cache",
     "XDG_DATA_HOME": "/home/vscode/.local/share"
-  }
+  },
+  "mounts": [
+    "source=${localEnv:HOME}/.claude,target=/home/vscode/.claude,type=bind"
+  ]
 }
 ```
 
+The `./claude-code` feature is declared in `.devcontainer/ci/devcontainer.json`, the config CI builds the image from, so there is no `features` block here -- and no `runArgs` either.
+
 ## Common Issues and Solutions
 
 ### Issue 1: Setup Wizard Runs on Every Container Rebuild
@@ -89,6 +90,9 @@ claude  # Should go straight to interactive mode without wizard
 OAuth callback server runs inside container on a random port (e.g., `localhost:35673`). Your browser tries to connect to that port on the HOST, but the container's port isn't accessible.
 
 **Solution:**
+Authenticate on the host, where the browser can reach the callback port, and let the container read the resulting credentials through the `~/.claude` bind mount. No OAuth flow then runs in the container at all.
+
+**Alternative, if you want the login to happen inside the container:**
 Add `--network=host` to devcontainer.json:
 
 ```json
@@ -99,11 +103,8 @@ Add `--network=host` to devcontainer.json:
 
 This makes the container share the host's network namespace, so ports inside the container are accessible from the host browser.
 
-**Trade-off:**
-Using `--network=host` gives the container full network access and may prevent VS Code extensions from installing (known issue: [#9212](https://github.com/microsoft/vscode-remote-release/issues/9212)).
-
-**Workaround if you can't use --network=host:**
-Authenticate on your host machine first, then credentials are shared via mounts.
+**What that costs:**
+VS Code extensions stop installing (known issue: [#9212](https://github.com/microsoft/vscode-remote-release/issues/9212)), the container gets full access to the host's network, and every port the container binds becomes a host port -- so two branch containers of the same repo collide on the first port they share.
 
 ### Issue 3: `claude --print` Works But Interactive `claude` Asks for Login
 
@@ -247,16 +248,15 @@ Look for:
 ```bash
 # On HOST
 docker inspect <container-id> | jq '.[0].HostConfig.NetworkMode'
-# Should show: "host"
+# "host" only if you opted into --network=host; otherwise the default bridge network
 ```
 
 ## Complete Setup Checklist
 
 When setting up a new workspace:
 
-- [ ] Node.js feature added to devcontainer.json
-- [ ] `./claude-code` feature added
-- [ ] `runArgs: ["--network=host"]` added
+- [ ] `./claude-code` feature declared in `.devcontainer/ci/devcontainer.json`, so the published image carries it
+- [ ] `claude` authenticated on the host, so no OAuth flow runs in the container
 - [ ] Environment variables added (CLAUDE_CONFIG_DIR, XDG_*)
 - [ ] Files exist on host: `.credentials.json`, `.claude.json`
 - [ ] File permissions: `chmod 600` on sensitive files

AGENTS.md

@@ -6,7 +6,7 @@ This project uses a devcontainer with pixi for environment management.
 
 ### Available Tools
 
-- **GitHub CLI (`gh`)**: Available via `pixi run gh` or directly if using a login shell. The container mounts the host's `~/.config/gh` directory, so if the user is authenticated on the host, authentication is shared automatically.
+- **GitHub CLI (`gh`)**: Available via `pixi run gh` or directly if using a login shell. Authentication arrives as `GH_TOKEN`, which `dl` forwards into every workspace it starts, taking it from `GH_TOKEN`, `GITHUB_TOKEN` or `gh auth token` -- whichever answers first. The container used to mount the host's `~/.config/gh` instead, which never worked: `gh` keeps its token in the system keyring, so the mounted `hosts.yml` carried no `oauth_token`. If the container was opened by something other than `dl` -- a plain `devpod up`, or VS Code's Reopen in Container -- it has no `gh` login and you have to export `GH_TOKEN` yourself.
 
 ### Running Commands