fwdit 0.1.2__tar.gz

fwdit-0.1.2/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.benchmarks/
+.coverage
+htmlcov/
+.DS_Store

fwdit-0.1.2/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: fwdit
+Version: 0.1.2
+Summary: Move coding work and agent sessions to remote compute
+Requires-Python: >=3.12
+Requires-Dist: prompt-toolkit>=3.0
+Requires-Dist: rich>=13
+Requires-Dist: tomlkit>=0.13
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# fwd
+
+**Move your coding project and agent session to remote compute.**
+
+`fwd` provisions or connects to a remote target, synchronizes the current project, prepares its toolchain, and starts a persistent shell, command, Claude Code, or Codex session in tmux. Disconnect your laptop and return later: the session, durable tasks, and logs remain available.
+
+```text
+laptop                                  remote SSH / RunPod / Lambda / Slurm
+project  ───────────── sync ──────────▶  project checkout
+agent context ──────── optional ──────▶  Claude or Codex state
+                                         tmux session + durable task manager
+terminal ◀────────── attach / stream ──  persistent work
+```
+
+## Install
+
+```sh
+uv tool install fwdit
+```
+
+Or try it without installing:
+
+```sh
+uvx --from fwdit fwd --help
+```
+
+Requires Python 3.12+, `ssh`, and `rsync` locally. Run `fwd doctor` to check target-specific requirements.
+
+## Quick start
+
+Run fwd from the project you want to move:
+
+```sh
+fwd                              # attach to this project's session, or create one interactively
+fwd up runpod codex              # launch Codex on RunPod; auto-attach in a human terminal
+fwd up --detach runpod codex     # launch Codex but stay in the local terminal
+fwd up --target work             # use a configured SSH/cloud/HPC target
+fwd up -- python train.py        # launch and stream a durable command
+fwd ls                           # inspect sessions and live status
+fwd attach SESSION               # reconnect from a human terminal
+```
+
+Bare `fwd` is the interactive reuse workflow. Agent launches auto-attach in a human terminal; pass `--detach` to stay local. Scripts and coding-agent environments remain non-attaching. Detach from tmux with `Ctrl-B D`.
+
+Need a saved target first?
+
+```sh
+fwd setup                        # interactive target setup
+fwd setup ssh --host my-box --target-name work
+fwd config --example runpod      # current generated config reference
+```
+
+Read [Getting started](docs/getting-started.md) for the full first-session walkthrough.
+
+## Choose a target
+
+- **SSH:** an existing host, direct address, or OpenSSH alias.
+- **RunPod:** CPU or GPU Pods with per-session persistent network volumes by default.
+- **Lambda Cloud:** GPU instances with persistent filesystems and local-only API credentials.
+- **Slurm:** allocations launched through persistent login-node tmux on shared scratch.
+
+See [Configuration and backends](docs/configuration.md#target-setup) for setup, storage, and lifecycle differences.
+
+## Common workflows
+
+### Run durable work
+
+```sh
+fwd send -- pytest -q
+fwd send --detach -- python train.py
+fwd send --ls --json
+fwd send TASK_ID                 # reattach to its log
+fwd send TASK_ID --stop          # cancel the task, not the session
+```
+
+Every command runs in remote tmux with a durable ID and log. Streaming returns the remote exit code; `Ctrl-C` cancels and `Ctrl-B` backgrounds the viewer.
+
+### Synchronize results
+
+```sh
+fwd diff                         # compare without changing either side
+fwd push                         # mirror local synchronized files to remote
+fwd pull outputs/                # additive download; never deletes local files
+```
+
+Sync honors `.gitignore`, `.fwdignore`, and configured exclusions. Upload includes `.git/` for remote agent continuity; pull and diff exclude Git metadata.
+
+### Forward a service
+
+```sh
+fwd ports 3000                   # localhost:3000 to remote localhost:3000
+fwd ports work 8080:3000
+fwd ports --ls
+fwd ports --close 3000
+```
+
+Forwards are loopback-only and persist through a managed SSH control connection.
+
+### Stop or destroy compute
+
+```sh
+fwd stop SESSION                 # stop compute and retain configured persistent storage
+fwd rm SESSION                   # permanently destroy remote resources
+```
+
+Both commands protect a reachable dirty remote Git worktree. `rm` is irreversible; force flags explicitly accept possible loss. See [Lifecycle safety](docs/commands.md#stop-remove-and-uninstall) before automating cleanup.
+
+## Coding-agent skill
+
+fwd ships an Agent Skills-compatible workflow for Codex, Claude Code, and other supporting agents. The first interactive invocation offers to install the bundled skill. It can also be installed directly:
+
+```sh
+npx skills add Sid-MB/fwd --skill fwd -g -a codex -a claude-code
+```
+
+Invoke it as `$fwd ...` in Codex or `/fwd ...` in Claude Code. See [Coding agents](docs/agents.md#install-the-fwd-skill) for behavior and credential guidance.
+
+## Documentation
+
+### User guide
+
+- [Getting started](docs/getting-started.md): installation, first launch, target setup, and the everyday workflow.
+- [Commands and lifecycle](docs/commands.md): durable tasks, synchronization, inspection, port forwarding, stopping, and removal.
+- [Configuration and backends](docs/configuration.md): config layers, SSH, RunPod, Lambda Cloud, Slurm, toolchains, and defaults.
+- [Coding agents](docs/agents.md): Claude/Codex transfer, follow-up turns, credentials, runtime policy, and skill installation.
+- [Troubleshooting](docs/troubleshooting.md): diagnostics, launch recovery, dirty worktrees, sync limits, and destructive operations.
+- [User documentation index](docs/README.md): the complete end-user map.
+
+The installed CLI is the authoritative option reference:
+
+```sh
+fwd --help
+fwd COMMAND --help
+fwd config --example
+fwd config --schema
+```
+
+### Developer guide
+
+- [Developer documentation index](dev-docs/README.md): architecture, provider notes, validation evidence, and repository map.
+- [Adding a target backend](dev-docs/adding-target-backends.md)
+- [Adding a project toolchain](dev-docs/adding-toolchains.md)
+- [Performance benchmarking](dev-docs/benchmarking.md)
+- [Contributing](CONTRIBUTING.md)

fwdit-0.1.2/README.md

@@ -0,0 +1,144 @@
+# fwd
+
+**Move your coding project and agent session to remote compute.**
+
+`fwd` provisions or connects to a remote target, synchronizes the current project, prepares its toolchain, and starts a persistent shell, command, Claude Code, or Codex session in tmux. Disconnect your laptop and return later: the session, durable tasks, and logs remain available.
+
+```text
+laptop                                  remote SSH / RunPod / Lambda / Slurm
+project  ───────────── sync ──────────▶  project checkout
+agent context ──────── optional ──────▶  Claude or Codex state
+                                         tmux session + durable task manager
+terminal ◀────────── attach / stream ──  persistent work
+```
+
+## Install
+
+```sh
+uv tool install fwdit
+```
+
+Or try it without installing:
+
+```sh
+uvx --from fwdit fwd --help
+```
+
+Requires Python 3.12+, `ssh`, and `rsync` locally. Run `fwd doctor` to check target-specific requirements.
+
+## Quick start
+
+Run fwd from the project you want to move:
+
+```sh
+fwd                              # attach to this project's session, or create one interactively
+fwd up runpod codex              # launch Codex on RunPod; auto-attach in a human terminal
+fwd up --detach runpod codex     # launch Codex but stay in the local terminal
+fwd up --target work             # use a configured SSH/cloud/HPC target
+fwd up -- python train.py        # launch and stream a durable command
+fwd ls                           # inspect sessions and live status
+fwd attach SESSION               # reconnect from a human terminal
+```
+
+Bare `fwd` is the interactive reuse workflow. Agent launches auto-attach in a human terminal; pass `--detach` to stay local. Scripts and coding-agent environments remain non-attaching. Detach from tmux with `Ctrl-B D`.
+
+Need a saved target first?
+
+```sh
+fwd setup                        # interactive target setup
+fwd setup ssh --host my-box --target-name work
+fwd config --example runpod      # current generated config reference
+```
+
+Read [Getting started](docs/getting-started.md) for the full first-session walkthrough.
+
+## Choose a target
+
+- **SSH:** an existing host, direct address, or OpenSSH alias.
+- **RunPod:** CPU or GPU Pods with per-session persistent network volumes by default.
+- **Lambda Cloud:** GPU instances with persistent filesystems and local-only API credentials.
+- **Slurm:** allocations launched through persistent login-node tmux on shared scratch.
+
+See [Configuration and backends](docs/configuration.md#target-setup) for setup, storage, and lifecycle differences.
+
+## Common workflows
+
+### Run durable work
+
+```sh
+fwd send -- pytest -q
+fwd send --detach -- python train.py
+fwd send --ls --json
+fwd send TASK_ID                 # reattach to its log
+fwd send TASK_ID --stop          # cancel the task, not the session
+```
+
+Every command runs in remote tmux with a durable ID and log. Streaming returns the remote exit code; `Ctrl-C` cancels and `Ctrl-B` backgrounds the viewer.
+
+### Synchronize results
+
+```sh
+fwd diff                         # compare without changing either side
+fwd push                         # mirror local synchronized files to remote
+fwd pull outputs/                # additive download; never deletes local files
+```
+
+Sync honors `.gitignore`, `.fwdignore`, and configured exclusions. Upload includes `.git/` for remote agent continuity; pull and diff exclude Git metadata.
+
+### Forward a service
+
+```sh
+fwd ports 3000                   # localhost:3000 to remote localhost:3000
+fwd ports work 8080:3000
+fwd ports --ls
+fwd ports --close 3000
+```
+
+Forwards are loopback-only and persist through a managed SSH control connection.
+
+### Stop or destroy compute
+
+```sh
+fwd stop SESSION                 # stop compute and retain configured persistent storage
+fwd rm SESSION                   # permanently destroy remote resources
+```
+
+Both commands protect a reachable dirty remote Git worktree. `rm` is irreversible; force flags explicitly accept possible loss. See [Lifecycle safety](docs/commands.md#stop-remove-and-uninstall) before automating cleanup.
+
+## Coding-agent skill
+
+fwd ships an Agent Skills-compatible workflow for Codex, Claude Code, and other supporting agents. The first interactive invocation offers to install the bundled skill. It can also be installed directly:
+
+```sh
+npx skills add Sid-MB/fwd --skill fwd -g -a codex -a claude-code
+```
+
+Invoke it as `$fwd ...` in Codex or `/fwd ...` in Claude Code. See [Coding agents](docs/agents.md#install-the-fwd-skill) for behavior and credential guidance.
+
+## Documentation
+
+### User guide
+
+- [Getting started](docs/getting-started.md): installation, first launch, target setup, and the everyday workflow.
+- [Commands and lifecycle](docs/commands.md): durable tasks, synchronization, inspection, port forwarding, stopping, and removal.
+- [Configuration and backends](docs/configuration.md): config layers, SSH, RunPod, Lambda Cloud, Slurm, toolchains, and defaults.
+- [Coding agents](docs/agents.md): Claude/Codex transfer, follow-up turns, credentials, runtime policy, and skill installation.
+- [Troubleshooting](docs/troubleshooting.md): diagnostics, launch recovery, dirty worktrees, sync limits, and destructive operations.
+- [User documentation index](docs/README.md): the complete end-user map.
+
+The installed CLI is the authoritative option reference:
+
+```sh
+fwd --help
+fwd COMMAND --help
+fwd config --example
+fwd config --schema
+```
+
+### Developer guide
+
+- [Developer documentation index](dev-docs/README.md): architecture, provider notes, validation evidence, and repository map.
+- [Adding a target backend](dev-docs/adding-target-backends.md)
+- [Adding a project toolchain](dev-docs/adding-toolchains.md)
+- [Performance benchmarking](dev-docs/benchmarking.md)
+- [Contributing](CONTRIBUTING.md)

fwdit-0.1.2/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: fwd
+description: Move a coding project or active Claude Code/Codex workflow to remote compute with fwd. Use for remote development, SSH, RunPod, Lambda Cloud, Slurm, extra CPU/GPU/memory, persistent remote agents, durable commands, synchronization, attaching, stopping, or destroying remote sessions.
+---
+
+# fwd remote development
+
+Use `fwd` to provision or reuse remote compute, synchronize the current project, prepare its tools, and run a persistent coding agent or command in tmux. Invoking this skill means the user wants fwd used.
+
+## Workflow
+
+1. Preserve the user's task, requested target, hardware, and shutdown requirements. Use the caller's agent (`codex` from Codex, `claude` from Claude) unless the user specifies another.
+2. If a provider machine must be chosen, inspect exact values before launch with `fwd up --machines` or `fwd up TARGET --machines`. Prefer CPU unless the user requests a GPU; never guess or abbreviate a provider identifier.
+3. Launch without taking over the terminal: `fwd up --detach --agent AGENT`, adding `--target TARGET` and `--machine MACHINE` only when selected. Never use a bare/reuse/attach form as a tool call.
+4. Read the exact session name and live state from `fwd ls --json`.
+5. Send the preserved task with `fwd send --name SESSION agent "TASK"`. Stream and iterate by default; use `--detach` only when the user asks to background the task.
+6. Inspect changed work with `fwd diff -q SESSION`, use `fwd diff SESSION` when details matter, and retrieve accepted files with `fwd pull --name SESSION`.
+7. Report the result and exact commands the user may need, especially `fwd attach SESSION`, `fwd send --name SESSION --ls`, and `fwd stop SESSION`.
+
+If setup is required, follow the exact flags printed by fwd. Do not open an interactive setup wizard or invent target values.
+
+For a requested shell command instead of agent work, use `fwd send --name SESSION -- COMMAND...`. Reattach with `fwd send --name SESSION TASK_ID`; cancel only that task with `fwd send --name SESSION TASK_ID --stop`.
+
+If `fwd` is unavailable, install the published distribution with `uv tool install fwdit`. If `uv` is unavailable, report that Python 3.12+, `uv`, `ssh`, and `rsync` are required instead of improvising another installer.
+
+## Safe automation
+
+- Prefer `--json` for `fwd ls`, `fwd doctor`, `fwd info`, and task listings. Diagnostics remain on stderr.
+- Never run bare `fwd`, `fwd TARGET`, `fwd attach`, `fwd a`, `fwd up --reuse`, or `fwd up --attach` as a tool call; they can take over a human terminal. Hand the exact attach command to the user.
+- Do not use `--restart` unless the user authorizes restarting stopped billable compute.
+- Do not use `--creds` unless the user authorizes copying live Claude credentials. GitHub setup defaults on; use `--no-setup-github` when credentials must stay local.
+- Never force `stop`, `rm`, or stop-after past a dirty or unreachable worktree unless the user explicitly accepts losing remote-only changes.
+- Never run `fwd rm --all --force` unless the user explicitly requests destruction of every tracked remote resource.
+- Run `fwd uninstall --force` only for an explicit local-uninstall request after explaining that it does not destroy remote resources; prefer `fwd rm --all` first.
+- Prefer `fwd diff -q` before push or pull. Exit 0 means synchronized, 1 different, and 2 error.
+- If upload exceeds `sync.max_size_gb`, confirm the directory is intentional before using the exact project-scoped limit command printed by fwd.
+- Missing `npx` or a failed optional skill refresh must not block normal fwd commands.
+- If preparation fails after provisioning and sync, give the human `fwd attach SESSION --raw` for a recovery shell. This does not authorize restarting stopped compute.
+
+## Stop after work
+
+For supported backends, use remote-owned shutdown so it survives local disconnection:
+
+```sh
+fwd up --stop-after -- COMMAND...
+fwd send --name SESSION --stop-after agent "TASK"
+fwd send --name SESSION stopafter
+fwd send --name SESSION cancel stopafter
+```
+
+Confirm the lifecycle task with `fwd send --name SESSION --ls --json`. Stop-after refuses a dirty remote worktree; never force it without explicit acceptance of data loss.
+
+Lambda does not support remote stop-after because its broad API key stays local. Retrieve durable results, then tell the user to run `fwd stop SESSION` from a connected machine.
+
+## Useful commands
+
+```sh
+fwd up --detach --target runpod --agent codex
+fwd up --detach --new --target runpod --agent codex
+fwd up -- COMMAND...
+fwd send --name SESSION agent "TASK"
+fwd send --name SESSION -- COMMAND...
+fwd send --name SESSION --ls --json
+fwd diff -q SESSION
+fwd pull --name SESSION outputs/
+fwd ls --all-projects --json
+fwd doctor --json
+```
+
+## References
+
+- Read [targets and configuration](references/targets-and-config.md) for resolution, setup, defaults, machines, and backend behavior.
+- Read [commands and lifecycle](references/commands-and-lifecycle.md) for launch, durable tasks, synchronization, ports, attachment, stopping, and destruction.
+- Read [agent transfer](references/agent-transfer.md) before launching Claude Code or Codex when transcripts, settings, skills, authentication, or remote control matter.
+
+`fwd --help` and `fwd COMMAND --help` are authoritative for the installed version.

fwdit-0.1.2/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "fwd Remote Development"
+  short_description: "Move coding work to remote compute"
+  default_prompt: "Use $fwd to continue this project on a remote machine."
+policy:
+  allow_implicit_invocation: true

fwdit-0.1.2/dev-docs/README.md

@@ -0,0 +1,39 @@
+# fwd developer documentation
+
+This folder contains architecture, extension, validation, and implementation notes for contributors working on fwd.
+
+## Extend fwd
+
+- [Adding a target backend](adding-target-backends.md): backend contract, configuration schema, lifecycle safety, registration, and verification.
+- [Adding a project toolchain](adding-toolchains.md): detection, requirements, installation, registration, and testing.
+
+## Understand provider implementations
+
+- [RunPod notes](runpod-notes.md): observed `runpodctl` behavior, endpoint churn, persistence, and fixtures.
+- [Lambda Cloud notes](lambda-notes.md): API, credential handling, deterministic ownership, storage, and lifecycle.
+- [Slurm notes](slurm-notes.md): login-node tmux, allocation scripts, path guards, and shared scratch.
+
+## Validation and performance
+
+- [Live end-to-end report](live-e2e-report.md): dated RunPod validation evidence and discovered regressions.
+- [Session transfer notes](session-transfer-notes.md): Claude transcript relocation experiment and encoding rules.
+- [Performance benchmarking](benchmarking.md): in-process command benchmarks and baseline comparison.
+
+## Repository map
+
+- `src/fwd/backends/`: provider lifecycle implementations.
+- `src/fwd/toolchains/` and `src/fwd/tooling.py`: project detection and remote requirements.
+- `src/fwd/ops/`: launch, attach, synchronization, lifecycle, and task orchestration.
+- `src/fwd/agents/`: Claude and Codex transfer/runtime integrations.
+- `tests/`: offline unit and integration tests; provider fixtures are under `tests/fixtures/`.
+- `references/`: compact references packaged with the coding-agent skill, not the end-user documentation site.
+
+## Development workflow
+
+```sh
+uv sync
+uv run pytest
+uv run fwd --help
+```
+
+See [CONTRIBUTING.md](../CONTRIBUTING.md) for contribution and publishing policy. User-facing behavior belongs in [docs](../docs/README.md), and concise project orientation belongs in the [top-level README](../README.md).

fwdit-0.1.2/docs/README.md

@@ -0,0 +1,20 @@
+# fwd user guide
+
+This folder contains the user documentation for `fwd`. Start with the guide that matches what you want to do:
+
+- [Getting started](getting-started.md): install fwd, create a target, and launch your first remote session.
+- [Commands and lifecycle](commands.md): launch, attach, run durable tasks, synchronize files, forward ports, stop, and remove sessions.
+- [Configuration and backends](configuration.md): layered configuration, SSH, RunPod, Lambda Cloud, Slurm, defaults, and project setup.
+- [Coding agents](agents.md): move Claude Code or Codex work, send follow-up turns, manage credentials, and install the fwd skill.
+- [Troubleshooting](troubleshooting.md): diagnose failures, recover partial launches, and avoid data loss.
+
+The installed CLI is the authoritative option reference:
+
+```sh
+fwd --help
+fwd COMMAND --help
+fwd config --example
+fwd config --schema
+```
+
+Contributing to fwd? See the [developer documentation](../dev-docs/README.md).

fwdit-0.1.2/pyproject.toml

@@ -0,0 +1,47 @@
+[project]
+name = "fwdit"
+dynamic = ["version"]
+description = "Move coding work and agent sessions to remote compute"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "prompt-toolkit>=3.0",
+    "typer>=0.12",
+    "rich>=13",
+    "tomlkit>=0.13",
+]
+
+[project.scripts]
+fwd = "fwd.cli:entrypoint"
+
+[dependency-groups]
+dev = ["pytest>=8"]
+
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+# The shared release workflow creates the next vX.Y.Z tag before building, so the wheel, sdist, Git tag, and GitHub Release all receive the same immutable version.
+source = "vcs"
+
+[tool.hatch.version.raw-options]
+# Source archives without Git metadata still expose a valid diagnostic version instead of failing to build.
+fallback_version = "0.0.0"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/fwd"]
+
+# bootstrap.sh must land inside the installed package so remote.BOOTSTRAP_PATH can resolve it via importlib.resources.
+[tool.hatch.build.targets.wheel.force-include]
+"src/fwd/scripts/bootstrap.sh" = "fwd/scripts/bootstrap.sh"
+"src/fwd/scripts/codex_tui_send.py" = "fwd/scripts/codex_tui_send.py"
+"SKILL.md" = "fwd/SKILL.md"
+"agents" = "fwd/skill_agents"
+"references" = "fwd/references"
+
+[tool.hatch.build.targets.sdist]
+include = ["src/fwd", "tests", "README.md", "/SKILL.md", "/agents", "/references"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

fwdit-0.1.2/references/agent-transfer.md

@@ -0,0 +1,83 @@
+# Claude Code and Codex transfer
+
+## Contents
+
+- Shared behavior
+- Claude Code
+- Codex
+- Authentication
+- Human handoff
+
+## Shared behavior
+
+Both magic commands synchronize the project, bootstrap remote tooling, start a persistent tmux session, and auto-attach only from a human terminal:
+
+```sh
+fwd up --target TARGET --agent claude
+fwd up --target TARGET --agent codex
+```
+
+Agents should run them without `--attach`. Non-interactive detection keeps the launch in the background.
+
+On RunPod, fwd prepares agent state before tool installation because `/root` is erased on every stop. GPU pods keep
+`~/.claude` or `~/.codex` beneath the persistent tool prefix and recreate the home symlink on relaunch, so remote
+authentication, conversations, settings, and Codex's managed standalone payload survive. CPU pods have no persistent
+volume; their full relaunch reconstructs local inputs but cannot retain state that existed only on the stopped pod.
+
+After launch, communicate with the running remote conversation through durable send tasks:
+
+```sh
+fwd send agent --detach "run the tests and fix failures"
+fwd send --ls --json
+fwd send TASK_ID
+fwd send TASK_ID --stop
+```
+
+Use `--immediate MESSAGE` when a new instruction should cancel and replace the active turn. A plain message queues
+behind an active managed turn. Send-task cancellation never stops the fwd session or its remote compute.
+
+## Claude Code
+
+The default `--session` mode moves the real local transcript and asks remote Claude to resume it. Transfer failures degrade to a plain Claude launch with a warning.
+
+`--handoff` replaces transcript transfer with a generated `HANDOFF.md`; use it only when the user requests a summary handoff. `--user-config` uploads portable Claude configuration while excluding credentials and history.
+
+## Codex
+
+Codex receives portable settings, configuration, and skills. It does not receive the current Codex transcript or authentication. Tell the user that the remote agent begins with the synchronized project and personal workflow configuration, not the local conversation.
+
+Once remote Codex has started, `fwd send agent MESSAGE` resumes its most recent remote project conversation through
+Codex's JSONL non-interactive interface. Human terminals receive concise text/tool events; non-interactive callers
+receive the original machine-readable event stream.
+
+Use JSON output and non-attaching commands when Codex is driving fwd:
+
+```sh
+fwd doctor --json
+fwd up codex --target TARGET
+fwd ls --json
+fwd diff -q TARGET
+```
+
+## Authentication
+
+Prefer logging in on the remote machine for coding-agent authentication. `--creds` writes a live Claude OAuth token to remote disk and requires explicit authorization in the current conversation. Codex authentication is never copied.
+
+GitHub authentication defaults on for development VMs and can be disabled with `[github] auth = false` or
+`--no-setup-github`. Fwd resolves `GH_TOKEN`, `GITHUB_TOKEN`, the active local gh account, Git's credential helper,
+then `~/.netrc`; an interactive caller can paste a PAT as the final fallback. It streams the selected credential to remote standard
+input, configures HTTPS Git access, and persists the remote credential on RunPod volumes. The token never enters
+project files, argv, logs, config, or session state. A direct `fwd send git push`, any sent coding-agent turn, and
+`fwd attach` can repair an older session in place. Do not describe `fwd pull && git push` as a way to transfer a remote
+commit: pull intentionally omits `.git/`. It can retrieve uncommitted files for a new local commit; preserving an
+existing remote commit requires a remote push or an explicitly exported patch or Git bundle.
+
+## Human handoff
+
+After launch, report the exact resolved target/session and tell the human:
+
+```sh
+fwd attach SESSION
+```
+
+If the user wants a result without attaching, use `fwd send agent`, `fwd send -- COMMAND`, or `fwd pull`.