🤖 feat: add coder-docs Mux agent skill with offline docs snapshot (#21)

## Summary

Adds a new Mux agent skill (`coder-docs`) that bundles a text-only
offline snapshot of the `coder/coder` documentation, enabling future Mux
instances to answer "how does Coder do X?" without pasting the entire
docs corpus into context.

## Background

When working in this repo, agents frequently need to reference Coder's
documentation (API behavior, deployment options, template authoring,
etc.). Without a local skill, they either hallucinate or require
expensive web fetches. This skill provides progressive-disclosure access
through a generated navigation tree and ~4.5MB of committed Markdown
docs.

## Implementation

### New files
- **`hack/gen-coder-docs-skill/main.go`** — Go CLI tool (stdlib only)
that:
- Syncs a text-only docs snapshot from upstream `coder/coder/docs/`
(excluding images)
  - Parses `manifest.json` and renders a hierarchical docs tree
  - Injects generated content between markers in `SKILL.md`
  - Writes `SNAPSHOT.json` with provenance metadata
- Defensive: fails fast on missing files, bad markers, unreferenced
paths
- **`hack/update-coder-docs-skill.sh`** — Shell script that
clones/updates `coder/coder` into `tmpfork/` and runs the generator
- **`.mux/skills/coder-docs/SKILL.md`** — Skill definition with
generated navigation tree (415 routes)
- **`.mux/skills/coder-docs/NOTICE.md`** — Licensing attribution
- **`.mux/skills/coder-docs/LICENSE`** — AGPL-3.0 (upstream license)
- **`.mux/skills/coder-docs/references/docs/`** — Committed snapshot
(~4.5MB text-only)

### Modified files
- **`Makefile`** — Added `update-coder-docs-skill` target
- **`AGENTS.md`** — Added skill reference and update command

## Validation

- `make build` ✅
- `make test` ✅
- `make verify-vendor` ✅
- `GOFLAGS=-mod=vendor go vet ./...` ✅
- `make update-coder-docs-skill` ✅ (end-to-end generation from upstream)
- Verified: no images copied, all manifest routes resolve, markers
populated

## Risks

Low risk — this is additive infrastructure (new skill + generator). No
existing code paths are modified. The snapshot is committed but can be
refreshed at any time via `make update-coder-docs-skill`.

---

<details>
<summary>📋 Implementation Plan</summary>

# Plan: Convert `coder/coder` docs into a Mux Agent Skill (`coder-docs`)

## Context / Why

We want a **project-local agent skill** that gives Mux agents
**progressive-disclosure access** to the `coder/coder` documentation:

- Offline(ish) access via files committed under
`.mux/skills/.../references/`.
- A deterministic, auto-generated **docs index tree** (like Mux’s
built-in `mux-docs` skill) so agents can quickly locate relevant pages.
- A repeatable **update script** that refreshes the snapshot from
upstream `coder/coder` into this repo.

This enables future Mux instances working in this repo to answer “how
does Coder do X?” without pasting the entire docs corpus into context.

## Evidence (what we verified)

- Mux’s built-in docs skill is generated via markers + nav parsing:
- `tmpfork/mux/scripts/gen_builtin_skills.ts` (injects `DOCS_TREE`
between `<!-- BEGIN ... -->` markers; bundles docs).
- `coder/coder` docs are file-based Markdown with a machine-readable
navigation tree:
- `tmpfork/coder/docs/manifest.json` (recursive `routes[]` with `title`,
`description`, `path`, optional `children`).
- Example doc format: `tmpfork/coder/docs/install/index.md` (Markdown
with some inline HTML; no YAML frontmatter).
- Size constraints:
  - `tmpfork/coder/docs` is ~89MB total, but `docs/images` is ~85MB.
- Text-only docs (excluding `images/`) are ~4.5MB, which is feasible to
commit into `.mux/skills/.../references/`.
- Licensing note:
- `tmpfork/coder/LICENSE` is AGPL-3.0. Vendoring docs requires
intentional attribution/notice.

## Implementation details

### 1) Add a new skill directory: `.mux/skills/coder-docs/`

Create a new skill named **`coder-docs`**:

- `.mux/skills/coder-docs/SKILL.md`
- `.mux/skills/coder-docs/references/docs/` (generated snapshot;
committed)

#### `SKILL.md` (template + generated sections)

Keep the file mostly static, but with two generated blocks updated by
the update script:

- `SNAPSHOT` block: what upstream commit this snapshot came from.
- `DOCS_TREE` block: a hierarchical index derived from
`docs/manifest.json`.

Template skeleton:

```md
---
name: coder-docs
description: Index + offline snapshot of coder/coder documentation (progressive disclosure).
---

# Coder Docs

This skill bundles a text-only snapshot of the documentation from `coder/coder`.

## How to use

- Use the generated **Docs tree** below to locate a topic, then read the exact page:

```ts
agent_skill_read_file({
  name: "coder-docs",
  filePath: "references/docs/install/docker.md",
});
```

- To understand the full navigation source-of-truth, read the manifest:

```ts
agent_skill_read_file({
  name: "coder-docs",
  filePath: "references/docs/manifest.json",
});
```

- If you need to keyword-search locally (outside the skill tool), use ripgrep in the repo:

```bash
rg -n "<keyword>" .mux/skills/coder-docs/references/docs
```

## Snapshot

<!-- BEGIN SNAPSHOT -->
<!-- END SNAPSHOT -->

## Docs tree (auto-generated)

<!-- BEGIN DOCS_TREE -->
<!-- END DOCS_TREE -->
```

### 2) Add an update script: `hack/update-coder-docs-skill.sh`

Goal: one command that (a) updates `tmpfork/coder` and (b) regenerates
the skill’s `references/docs/` snapshot + `SKILL.md` generated sections.

**Why `hack/`?** This repo already uses `hack/update-*.sh` for generated
artifacts.

#### Script responsibilities

1. **Dependency checks** (fail fast): `git`, `go`.
2. **Clone/update** `coder/coder` into `./tmpfork/coder`:
   - If missing: shallow clone.
- If present: `fetch` and `reset --hard` to a known ref (default:
`origin/main`).
3. **Run the Go generator** (`hack/gen-coder-docs-skill/main.go`) which:
- Refreshes the snapshot under `.mux/skills/coder-docs/references/docs/`
(wipes destination first to avoid stale files; copies `manifest.json` +
all `**/*.md`; **excludes** `docs/images/`).
- Regenerates the `DOCS_TREE` block in
`.mux/skills/coder-docs/SKILL.md`.
   - Writes snapshot metadata (upstream commit SHA + timestamp) to:
     - the `SNAPSHOT` block in `SKILL.md`, and
     - `references/docs/SNAPSHOT.json` (machine-readable).

#### Proposed script shape (pseudo-code)

```bash
#!/usr/bin/env bash
set -euo pipefail

ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
CODER_DIR="$ROOT/tmpfork/coder"
SKILL_DIR="$ROOT/.mux/skills/coder-docs"
DEST_DOCS_DIR="$SKILL_DIR/references/docs"

# 1) deps
command -v git >/dev/null
command -v go >/dev/null

# 2) clone/update
if [[ ! -d "$CODER_DIR/.git" ]]; then
  git clone --depth=1 https://github.com/coder/coder "$CODER_DIR"
else
  git -C "$CODER_DIR" fetch origin main --depth=1
  git -C "$CODER_DIR" reset --hard origin/main
fi
CODER_SHA="$(git -C "$CODER_DIR" rev-parse HEAD)"

# 3) sync docs snapshot + generate + inject (Go tool does it all)
cd "$ROOT"
GOFLAGS=-mod=vendor go run ./hack/gen-coder-docs-skill/main.go \
  --source-docs-root "$CODER_DIR/docs" \
  --dest-docs-root "$DEST_DOCS_DIR" \
  --skill-md "$SKILL_DIR/SKILL.md" \
  --coder-sha "$CODER_SHA" \
  --snapshot-out "$DEST_DOCS_DIR/SNAPSHOT.json"
```

### 3) Add the generator helper: `hack/gen-coder-docs-skill/main.go`

Implement the JSON parsing + marker injection logic in Go (stdlib only)
so it matches this repo’s primary language and avoids a Python runtime
dependency.

#### Generator requirements (defensive by default)

- **Fail fast** if `SKILL.md` markers are missing or malformed.
- **Sync snapshot** from `--source-docs-root` → `--dest-docs-root`:
  - wipe destination first (prevents stale docs),
  - copy `manifest.json` + all `**/*.md`,
  - skip `images/` and any non-markdown assets.
- **Fail fast** if a `manifest.json` route references a doc path that
does not exist under `--dest-docs-root` (after sync).
- Normalize newlines (`\r\n` → `\n`) for deterministic diffs.
- Use only the Go standard library (no `go.mod` / `vendor/` changes).

#### Core logic sketch

```go
type Manifest struct {
	Routes []Route `json:"routes"`
}

type Route struct {
	Title       string  `json:"title"`
	Description string  `json:"description"`
	Path        string  `json:"path"`
	Children    []Route `json:"children"`
}

func injectBlock(content, marker, block string) (string, error) {
	begin := "<!-- BEGIN " + marker + " -->"
	end := "<!-- END " + marker + " -->"
	bi := strings.Index(content, begin)
	ei := strings.Index(content, end)
	if bi == -1 || ei == -1 || ei < bi {
		return "", fmt.Errorf("missing markers for %s", marker)
	}
	before := content[:bi+len(begin)]
	after := content[ei:]
	return before + "\n" + strings.TrimRight(block, "\n") + "\n" + after, nil
}

func normalizeManifestPath(p string) (string, error) {
	if !strings.HasPrefix(p, "./") {
		return "", fmt.Errorf("expected manifest path starting with './': %q", p)
	}
	return strings.TrimPrefix(p, "./"), nil
}

func renderRoutes(routes []Route, indent int, out *[]string, docsRoot string) error {
	prefix := strings.Repeat("  ", indent)
	for _, r := range routes {
		rel, err := normalizeManifestPath(r.Path)
		if err != nil {
			return err
		}
		if _, err := os.Stat(filepath.Join(docsRoot, rel)); err != nil {
			return fmt.Errorf("missing doc referenced by manifest: %s: %w", rel, err)
		}

		title := strings.TrimSpace(r.Title)
		if title == "" {
			return fmt.Errorf("manifest route missing title for path %q", r.Path)
		}
		if len(r.Children) > 0 {
			title = "**" + title + "**"
		}

		suffix := ""
		if desc := strings.TrimSpace(r.Description); desc != "" {
			suffix = " — " + desc
		}

		*out = append(*out, fmt.Sprintf(
			"%s- %s (`%s`) → `references/docs/%s`%s",
			prefix, title, rel, rel, suffix,
		))

		if len(r.Children) > 0 {
			if err := renderRoutes(r.Children, indent+1, out, docsRoot); err != nil {
				return err
			}
		}
	}
	return nil
}
```

Output:
- `DOCS_TREE`: `strings.Join(lines, "\n")` after
`renderRoutes(manifest.Routes, 0, &lines, docsRoot)`.
- `SNAPSHOT`: short Markdown block like:
  - `Upstream: coder/coder@<sha>`
  - `Generated: <RFC3339 timestamp>`

### 4) Make it easy to run: add a Makefile target

Add a convenience target:

```make
.PHONY: update-coder-docs-skill
update-coder-docs-skill:
	bash ./hack/update-coder-docs-skill.sh
```

### 5) Make it discoverable (optional but recommended)

- Update `README.md` (or `AGENTS.md`) with a short “Mux skills” note:
  - Skill name: `coder-docs`
  - Update command: `make update-coder-docs-skill`

### 6) Licensing / attribution

Because `coder/coder` is AGPL-3.0:

- Add `.mux/skills/coder-docs/NOTICE.md` describing:
  - what is vendored,
  - where it came from (repo URL + commit SHA),
  - and the applicable license.
- Include a copy of the upstream AGPL license text within the skill
directory (e.g. `.mux/skills/coder-docs/LICENSE`) so the vendored-docs
subtree is self-describing.

<details>
<summary>Why call this out?</summary>

Vendoring content across repositories can have license implications.
This plan keeps the skill directory explicit about provenance and
license so downstream consumers are not surprised.

</details>

## Validation / Acceptance Criteria

After implementation (Exec mode):

1. Run `make update-coder-docs-skill`.
2. Confirm files exist:
- `.mux/skills/coder-docs/SKILL.md` contains populated `SNAPSHOT` +
`DOCS_TREE` blocks.
   - `.mux/skills/coder-docs/references/docs/manifest.json` exists.
   - `.mux/skills/coder-docs/references/docs/install/docker.md` exists.
3. Confirm **no images** were copied:
   - `.mux/skills/coder-docs/references/docs/images/` should not exist.
4. Confirm integrity checks pass:
   - every `manifest.json` `path` exists under `references/docs/`.
5. (Mux smoke test) In a Mux session, verify:
   - `agent_skill_read({ name: "coder-docs" })` works.
- `agent_skill_read_file({ name: "coder-docs", filePath:
"references/docs/install/index.md" })` returns content.

Success looks like: a committed `.mux/skills/coder-docs` directory with
a small (~5MB) text snapshot + deterministic index, and a single update
script that can refresh it from upstream.

</details>

---
_Generated with `mux` • Model: `anthropic:claude-opus-4-6` • Thinking:
`xhigh` • Cost: `$1.41`_

<!-- mux-attribution: model=anthropic:claude-opus-4-6 thinking=xhigh
costs=1.41 -->

Author: ThomasK33

.mux/skills/coder-docs/LICENSE

@@ -0,0 +1,15 @@
+# Notice
+
+This directory contains a text-only snapshot of the documentation from
+[coder/coder](https://github.com/coder/coder).
+
+- **Source repository**: https://github.com/coder/coder
+- **License**: GNU Affero General Public License v3.0 (AGPL-3.0)
+- **What is vendored**: Markdown documentation files and `manifest.json` only
+  (images and other binary assets are excluded).
+- **Upstream commit**: See `references/docs/SNAPSHOT.json` for the exact commit SHA.
+
+The vendored content is used solely to provide offline documentation access
+for AI development agents working in this repository.
+
+See `LICENSE` in this directory for the full license text.

.mux/skills/coder-docs/NOTICE.md

@@ -0,0 +1,146 @@
+# About
+
+<!-- Warning for docs contributors: The first route in manifest.json must be titled "About" for the static landing page to work correctly. -->
+
+Coder is a self-hosted, open source, cloud development environment that works
+with any cloud, IDE, OS, Git provider, and IDP.
+
+![Screenshots of Coder workspaces and connections](./images/hero-image.png)_Screenshots of Coder workspaces and connections_
+
+Coder is built on common development interfaces and infrastructure tools to
+make the process of provisioning and accessing remote workspaces approachable
+for organizations of various sizes and stages of cloud-native maturity.
+
+## IDE support
+
+![IDE icons](./images/ide-icons.svg)
+
+You can use:
+
+- Any Web IDE, such as
+
+  - [code-server](https://github.com/coder/code-server)
+  - [JetBrains Projector](https://github.com/JetBrains/projector-server)
+  - [Jupyter](https://jupyter.org/)
+  - And others
+
+- Your existing remote development environment:
+
+  - [JetBrains Gateway](https://www.jetbrains.com/remote-development/gateway/)
+  - [VS Code Remote](https://code.visualstudio.com/docs/remote/ssh-tutorial)
+  - [Emacs](./user-guides/workspace-access/emacs-tramp.md)
+
+- A file sync such as [Mutagen](https://mutagen.io/)
+
+## Why remote development
+
+Remote development offers several benefits for users and administrators, including:
+
+- **Increased speed**
+
+  - Server-grade cloud hardware speeds up operations in software development, from
+    loading the IDE to compiling and building code, and running large workloads
+    such as those for monolith or microservice applications.
+
+- **Easier environment management**
+
+  - Built-in infrastructure tools such as Terraform, nix, Docker, Dev Containers, and others make it easier to onboard developers with consistent environments.
+
+- **Increased security**
+
+  - Centralize source code and other data onto private servers or cloud services instead of local developers' machines.
+  - Manage users and groups with [SSO](./admin/users/oidc-auth/index.md) and [Role-based access controlled (RBAC)](./admin/users/groups-roles.md#roles).
+
+- **Improved compatibility**
+
+  - Remote workspaces can share infrastructure configurations with other
+    development, staging, and production environments, reducing configuration
+    drift.
+
+- **Improved accessibility**
+  - Connect to remote workspaces via browser-based IDEs or remote IDE
+    extensions to enable developers regardless of the device they use, whether
+    it's their main device, a lightweight laptop, Chromebook, or iPad.
+
+Read more about why organizations and engineers are moving to remote
+development on [our blog](https://coder.com/blog), the
+[Slack engineering blog](https://slack.engineering/development-environments-at-slack),
+or from [OpenFaaS's Alex Ellis](https://blog.alexellis.io/the-internet-is-my-computer/).
+
+## Why Coder
+
+The key difference between Coder and other remote IDE platforms is the added
+layer of infrastructure control.
+This additional layer allows admins to:
+
+- Simultaneously support ARM, Windows, Linux, and macOS workspaces.
+- Modify pod/container specs, such as adding disks, managing network policies, or
+  setting/updating environment variables.
+- Use VM or dedicated workspaces, developing with Kernel features (no container
+  knowledge required).
+- Enable persistent workspaces, which are like local machines, but faster and
+  hosted by a cloud service.
+
+## How much does it cost?
+
+Coder is free and open source under
+[GNU Affero General Public License v3.0](https://github.com/coder/coder/blob/main/LICENSE).
+All developer productivity features are included in the Open Source version of
+Coder.
+A [Premium license is available](https://coder.com/pricing#compare-plans) for enhanced
+support options and custom deployments.
+
+## How does Coder work
+
+Coder workspaces are represented with Terraform, but you don't need to know
+Terraform to get started.
+We have a [database of production-ready templates](https://registry.coder.com/templates)
+for use with AWS EC2, Azure, Google Cloud, Kubernetes, and more.
+
+![Providers and compute environments](./images/providers-compute.png)_Providers and compute environments_
+
+Coder workspaces can be used for more than just compute.
+You can use Terraform to add storage buckets, secrets, sidecars,
+[and more](https://developer.hashicorp.com/terraform/tutorials).
+
+Visit the [templates documentation](./admin/templates/index.md) to learn more.
+
+## What Coder is not
+
+- Coder is not an infrastructure as code (IaC) platform.
+
+  - Terraform is the first IaC _provisioner_ in Coder, allowing Coder admins to
+    define Terraform resources as Coder workspaces.
+
+- Coder is not a DevOps/CI platform.
+
+  - Coder workspaces can be configured to follow best practices for
+    cloud-service-based workloads, but Coder is not responsible for how you
+    define or deploy the software you write.
+
+- Coder is not an online IDE.
+
+  - Coder supports common editors, such as VS Code, vim, and JetBrains,
+    all over HTTPS or SSH.
+
+- Coder is not a collaboration platform.
+
+  - You can use Git with your favorite Git platform and dedicated IDE
+    extensions for pull requests, code reviews, and pair programming.
+
+- Coder is not a SaaS/fully-managed offering.
+  - Coder is a [self-hosted](<https://en.wikipedia.org/wiki/Self-hosting_(web_services)>)
+    solution.
+    You must host Coder in a private data center or on a cloud service, such as
+    AWS, Azure, or GCP.
+
+## Using Coder v1?
+
+If you're a Coder v1 customer, view [the v1 documentation](https://coder.com/docs/v1)
+or [the v2 migration guide and FAQ](https://coder.com/docs/v1/guides/v2-faq).
+
+## Up next
+
+- [Template](./admin/templates/index.md)
+- [Installing Coder](./install/index.md)
+- [Quickstart](./tutorials/quickstart.md) to try Coder out for yourself.

.mux/skills/coder-docs/SKILL.md

@@ -0,0 +1,5 @@
+{
+  "upstream_repo": "coder/coder",
+  "upstream_sha": "342d2e4bedf60b7d73bf11310e290871986ca874",
+  "generated_at": "2026-02-10T08:26:19Z"
+}

.mux/skills/coder-docs/references/docs/README.md

@@ -0,0 +1,32 @@
+# AI Contribution Guidelines
+
+This document defines rules for contributions where an AI system is the primary author of the code (i.e., most of the pull request was generated by AI).
+It applies to all Coder repositories and is a supplement to the [existing contributing guidelines](./CONTRIBUTING.md), not a replacement.
+
+For minor AI-assisted edits, suggestions, or completions where the human contributor is clearly the primary author, these rules do not apply — standard contributing guidelines are sufficient.
+
+## Disclosure
+
+Contributors must **disclose AI involvement** in the pull request description whenever these guidelines apply.
+
+## Human Ownership & Attribution
+
+- All pull requests must be opened under **user accounts linked to a human**, and not an application ("bot account").
+- Contributors are personally accountable for the content of their PRs, regardless of how it was generated.
+
+## Verification & Evidence
+
+All AI-assisted contributions require **manual verification**.
+Contributions without verification evidence will be rejected.
+
+- Test your changes yourself. Don’t assume AI is correct.
+- Provide screenshots showing that the change works as intended.
+  - For visual/UI changes: include before/after screenshots.
+  - For CLI or backend changes: include terminal or api output.
+
+## Why These Rules Exist
+
+Traditionally, maintainers assumed that producing a pull request required more effort than reviewing it.
+With AI-assisted tools, the balance has shifted: generating code is often faster than reviewing it.
+
+Our guidelines exist to safeguard maintainers’ time, uphold contributor accountability, and preserve the overall quality of the project.

.mux/skills/coder-docs/references/docs/SNAPSHOT.json

@@ -0,0 +1,77 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, sex characteristics, gender identity and
+expression, level of experience, education, socio-economic status, nationality,
+personal appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+- The use of sexualized language or imagery and unwelcome sexual attention or
+  advances
+- Trolling, insulting/derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, or to ban temporarily or permanently any
+contributor for other behaviors that they deem inappropriate, threatening,
+offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at <opensource@coder.com>. All complaints
+will be reviewed and investigated and will result in a response that is deemed
+necessary and appropriate to the circumstances. The project team is obligated to
+maintain confidentiality with regard to the reporter of an incident. Further
+details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 1.4, available at
+<https://www.contributor-covenant.org/version/1/4/code-of-conduct.html>
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see
+<https://www.contributor-covenant.org/faq>