Skip to content

Commit 9bfd168

Browse files
EdwardAngertEdwardAngert
committed
init coder-docs-writing repo
0 parents  commit 9bfd168

11 files changed

+824
-0
lines changed

‎.gitattributes

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# Normalize all line endings to LF
2+
* text=auto eol=lf
3+
4+
# Treat all markdown files as UTF-8
5+
*.md text working-tree-encoding=UTF-8
6+
7+
# Enforce consistent diffing
8+
*.md diff=markdown

‎.github/workflows/lint-markdown.yml

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
name: Markdown Lint
2+
3+
on:
4+
pull_request:
5+
push:
6+
branches: [main]
7+
8+
jobs:
9+
markdownlint:
10+
runs-on: ubuntu-latest
11+
steps:
12+
- uses: actions/checkout@v4
13+
14+
- name: Set up Node
15+
uses: actions/setup-node@v4
16+
with:
17+
node-version: 20
18+
19+
- name: Install markdownlint-cli
20+
run: npm install -g markdownlint-cli
21+
22+
- name: Lint markdown
23+
run: markdownlint '**/*.md' --config .markdownlint.jsonc

‎.gitignore

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# OS/system junk
2+
.DS_Store
3+
Thumbs.db
4+
5+
# Editor files
6+
*.swp
7+
*.swo
8+
*.bak
9+
*.tmp
10+
.idea/
11+
.vscode/
12+
13+
# Logs or session data
14+
*.log
15+
16+
# Generated or temporary files
17+
*.out
18+
*.pdf
19+
*.html
20+
*.zip
21+
22+
# Optional: AI output artifacts if used
23+
ai-output/

‎README.md

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
# Doc Writer Knowledgebase for Coder.com
2+
3+
## Suggested Prompt for Claude Code and ChatGPT
4+
5+
To ensure consistent and context-aware assistance from ChatGPT or Claude Code, use the following prompt when starting a session:
6+
7+
```md
8+
You are assisting with technical documentation for the open source Coder project (https://github.com/coder/coder). You should follow the rules and preferences outlined in these files:
9+
10+
- style-guide.md (formatting and tone rules)
11+
- architecture-notes.md (high-level architecture of the product)
12+
- doc-template.md (content structure scaffolds)
13+
- snippet-library.md (reusable CLI/YAML/config blocks)
14+
- ai-project-notes.md (recent work log and in-progress ideas)
15+
- claude-code-config.md (rules for Claude's behavior)
16+
17+
You are not responsible for copyediting or tone unless asked; focus on:
18+
- technical accuracy (based on the codebase and documented architecture)
19+
- adherence to file placement and structure
20+
- verifying commands, parameters, and file references
21+
- following our markdown and terminology conventions
22+
23+
Do not use emojis in headings or list items. Use relative paths in links. If you're unsure, ask before making assumptions.
24+
```
25+
26+
You can paste this prompt directly into Claude Code or ChatGPT (Pro) and then upload or paste relevant files as needed.
27+
28+
---
29+
30+
Welcome to your personal and collaborative documentation-sidecar knowledgebase. This repo is intended to assist and streamline your work on [Coder documentation](https://github.com/coder/coder), especially in collaboration with AI tools like ChatGPT and Claude Code.
31+
32+
This directory — `coder-docs-writing/` — is meant to live alongside the `coder/` and `coder.com/` repositories within your local workspace.
33+
34+
---
35+
36+
## Purpose
37+
This repo acts as a **persistent memory store** for markdown/style preferences, architectural understanding, and AI-generated notes. It is designed to:
38+
39+
- Serve as a **sidecar knowledgebase** for the primary maintainer (Edward Angert)
40+
- Act as an **AI Subject Matter Expert (AI-SME)** for use in LLM workflows
41+
- Be a **shared workspace** for coworkers to contribute insights, style clarifications, architecture notes, and documentation patterns
42+
43+
The goal is to reduce context-switching, enforce style and consistency, and enable teammates or AI to step in seamlessly.
44+
45+
---
46+
47+
## Structure
48+
49+
```
50+
coder-docs-writing/
51+
├── README.md # This file
52+
├── style-guide.md # Markdown and tone/style preferences
53+
├── architecture-notes.md # Evolving notes about the Coder architecture
54+
├── templates/
55+
│ ├── doc-template.md # Skeletons or starter templates
56+
│ └── snippet-library.md # Reusable markdown/YAML/code blocks
57+
├── ai-project-notes.md # AI-writable log for evolving notes
58+
├── integration/
59+
│ ├── chatgpt-config.md # Guidance for using ChatGPT effectively
60+
│ └── claude-code-config.md # SME config for Claude (merged from CLAUDE.md + CLAUDE_DOCS_GUIDELINES.md)
61+
```
62+
63+
Documentation paths should refer to content under `../coder/docs/`. Image assets are under `../coder/docs/images/`. Website rendering code is in `../coder.com/`.
64+
65+
---
66+
67+
## Getting Started
68+
69+
1. **Clone the repo locally** (or fork it for sandboxed edits):
70+
```bash
71+
git clone git@github.com:yourusername/coder-docs-writing.git ~/.coder-docs-writing
72+
```
73+
74+
2. **(Optional) Create a symlink for convenience**:
75+
```bash
76+
ln -s ~/.coder-docs-writing ~/Documents/coder-docs-writing
77+
```
78+
79+
3. **(Optional) Create a shell alias for quick access**:
80+
```bash
81+
alias dockb='cd ~/.coder-docs-writing && nvim'
82+
```
83+
84+
4. **Review or contribute to the shared files**:
85+
- Use `style-guide.md` to guide any edits or submissions.
86+
- Use `architecture-notes.md` to share system behavior or insights.
87+
- Use `ai-project-notes.md` for project context and session memory.
88+
- Use `claude-code-config.md` to align Claude’s output with established documentation expectations and Git/image handling workflows.
89+
90+
5. **For AI usage**, upload or reference the relevant files during prompts to ChatGPT or Claude.
91+
92+
---
93+
94+
## Example Use Case
95+
96+
Say you're documenting a new Coder feature and want to ensure style consistency:
97+
98+
1. Upload `style-guide.md` and `architecture-notes.md` to your LLM session.
99+
2. Paste in raw markdown from a WIP doc.
100+
3. Prompt: _"Review this content using my style guide and Coder architecture notes."_
101+
102+
Or:
103+
104+
4. After wrapping a long LLM session:
105+
Prompt: _"Summarize what we just discussed and add it to `ai-project-notes.md` in today's date section."_
106+
107+
Coworkers can also use the same context files when jumping in to help maintain consistency.
108+
109+
---
110+
111+
## Next Steps
112+
113+
- ✅ Populate `style-guide.md` and `doc-template.md` based on current habits
114+
- ✅ Start using `ai-project-notes.md` as a running journal with daily notes
115+
- 🔁 Invite team members to contribute and update key files collaboratively
116+
- ⏳ Optionally script or automate note updates from PRs, commits, or AI output
117+
- 📎 Claude config now reflects all previous Claude-specific guidance (including Git/image behavior and prompt strategy)
118+
119+
---
120+
121+
## Contributing to This Knowledgebase
122+
123+
This repo is meant to be shared across documentation contributors and AI assistants. Please follow these guidelines when editing or proposing changes:
124+
125+
### General Rules
126+
- **Do not use emojis** in headings or list items
127+
- **Use relative paths** for internal links and image references
128+
- All code blocks should have a language identifier (e.g., `bash`, `json`, `md`)
129+
- Refer to `style-guide.md` before formatting or revising content
130+
131+
### File Guidelines
132+
- `style-guide.md`: Contribute formatting rules, tone notes, or markdown patterns
133+
- `architecture-notes.md`: Document internal behavior of the Coder system
134+
- `ai-project-notes.md`: Add time-stamped entries summarizing decisions, quirks, or updates
135+
- `templates/`: Extend with new skeletons or reusable snippets
136+
- `integration/`: Do not remove AI configuration files — update with care
137+
138+
### Git Practices
139+
- Always branch from `main`
140+
- Use descriptive branch names (e.g., `fix/agent-notes`, `feat/add-provisioning-snippets`)
141+
- Keep PRs focused and small when possible
142+
143+
This keeps the repo clean, traceable, and AI-friendly.
144+
145+
---
146+
147+
Happy documenting — and collaborating!
148+
149+
---
150+
151+
**Maintainer:** Edward Angert
152+
**Context:** Coder.com Documentation
153+
**Last updated:** 2025-05-06

‎ai-project-notes.md

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# AI Project Notes
2+
3+
This is a running log of notes, observations, decisions, and refinements related to AI-assisted documentation work for the Coder codebase and documentation site. Use this as a shared memory between yourself and tools like ChatGPT and Claude.
4+
5+
> All entries should be dated. Use bullet points to capture brief notes, discoveries, or things to revisit. Prefer clarity over completeness.
6+
7+
---
8+
9+
## [2025-05-05] Initial Setup
10+
11+
- Created `coder-docs-writing` to serve as shared SME knowledgebase and AI sidecar.
12+
- Sourced content from existing files: `CLAUDE.md`, `CODER_ARCHITECTURE.md`, and `CLAUDE_DOCS_GUIDELINES.md`.
13+
- Adopted rule: **no emojis** in headings or list items.
14+
- Merged Claude-related guidelines into `integration/claude-code-config.md`.
15+
- Moved architecture overview into `architecture-notes.md`.
16+
- Style conventions are tracked in `style-guide.md` and adhere to markdownlint + Google + GitLab.
17+
18+
---
19+
20+
## [2025-05-06] Style & Template Refinement
21+
22+
- Added `doc-template.md` under `templates/` as a scaffold for new docs.
23+
- Enforced use of `<Image>` with relative paths and fixed pixel width.
24+
- Confirmed internal doc structure under `../coder/docs/` is stable:
25+
- User Guides → `guides/`
26+
- Admin Docs → `admin/`
27+
- Tutorials → `tutorials/`
28+
- Reference → `reference/` (auto-generated, do not edit)
29+
30+
---
31+
32+
## [TEMPLATE]
33+
34+
## [YYYY-MM-DD] Topic or Focus
35+
36+
- Bullet 1
37+
- Bullet 2
38+
- Optional action item or idea to follow up on
39+
40+
---
41+
42+
_Last updated: 2025-05-06_

‎architecture-notes.md

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
# Coder Architecture Reference
2+
3+
This document provides a high-level overview of the Coder backend, CLI, agent system, and documentation layout to support consistent and technically accurate documentation.
4+
5+
---
6+
7+
## 🏛️ Core Components
8+
9+
### Server Layer (`/coderd`)
10+
- HTTP + DRPC server defined in `coderd/coderd.go`
11+
- Manages API routes, authN/authZ, middleware, RBAC
12+
- Handles workspace operations, telemetry, and metrics
13+
14+
### CLI Layer (`/cmd`, `/cli`)
15+
- Entry point: `cmd/coder/main.go`
16+
- Uses command pattern for subcommands
17+
- Supports auth, session management, workspace & template ops
18+
19+
### Database Layer (`/coderd/database`)
20+
- PostgreSQL backend managed with `sqlc`
21+
- Implements retries, transactions, and migrations
22+
- Core tables: users, orgs, workspaces, templates, resources
23+
24+
### Agent System (`/agent`)
25+
- Runs in workspaces to manage connectivity and execution
26+
- Features: SSH, port forwarding, PTY sessions, metrics, script execution
27+
- Lifecycle: `init` → `connect` → `operate` → `shutdown`
28+
29+
### Provisioner System (`/provisionerd`)
30+
- Terraform-driven provisioning backend
31+
- Manages job queue, logs, build lifecycle, status updates
32+
33+
### Networking Stack (`/tailnet`, `/vpn`)
34+
- P2P networking via custom Tailscale-based Tailnet
35+
- Supports NAT traversal, DERP relays, VPN fallback
36+
- Provides secure agent–client tunnels via WireGuard
37+
38+
---
39+
40+
## 🧱 Template & Provisioning System
41+
42+
### Template Architecture
43+
- Templates = Terraform modules with Coder extensions
44+
- Key custom resources:
45+
- `coder_agent`, `coder_app`, `coder_script`, `coder_parameter`, `coder_metadata`
46+
- Versioned: Each version is immutable and linked to a provisioner job
47+
48+
### Provisioning Workflow
49+
1. **Version upload**: Terraform code added
50+
2. **Parse phase**: Metadata, parameters extracted
51+
3. **Plan phase**: Graph analysis, validation
52+
4. **Apply phase**: Provisioning, state capture, workspace mapping
53+
54+
---
55+
56+
## 🌐 Networking Details
57+
58+
### Tailnet Architecture
59+
- **Coordinator**: Peer connection orchestration
60+
- **Conn**: WireGuard session management and state
61+
- **Tunneling**: Secure connections w/ fallback to DERP
62+
63+
### Security Model
64+
- WireGuard encryption
65+
- DRPC token-based handshake
66+
- Auth scopes for client vs agent
67+
68+
### NAT Traversal
69+
- Auto-detects proxy behavior
70+
- Falls back to WebSockets or DERP
71+
- Monitors connection health + logs state
72+
73+
---
74+
75+
## ⚙️ Agent Lifecycle
76+
77+
1. **Init**: `agent.New()` starts services, sets up PTY, SSH
78+
2. **Connect**: Token exchange → DRPC → manifest fetch → tailnet join
79+
3. **Operate**: Connection handling, metrics, logs
80+
4. **Shutdown**: Graceful termination, shutdown scripts
81+
82+
Agent responsibilities include:
83+
- Shell and port access
84+
- Health checks
85+
- Scripted automation (startup/shutdown)
86+
- Resource monitoring
87+
88+
---
89+
90+
## 📁 Documentation Structure
91+
92+
Docs live in `../coder/docs/`, with sections:
93+
1. `about/` – What Coder is
94+
2. `install/` – Platform install guides
95+
3. `guides/` – End-user guidance
96+
4. `admin/` – Admin + template authoring docs
97+
5. `tutorials/` – Task-based guides, KB
98+
6. `reference/` – CLI + API docs (auto-generated)
99+
7. `contributing/` – Maintainer and contributor guide
100+
101+
The Coder website itself is rendered from `../coder.com/`.
102+
103+
---
104+
105+
## 🔁 Entity Relationships
106+
107+
- **Users → Organizations**: Each user can belong to many orgs
108+
- **Orgs → Templates**: Orgs own templates
109+
- **Templates → Workspaces**: Workspaces are created from template versions
110+
- **Workspaces → Agents**: Agents live in workspaces
111+
- **Agents → Resources**: Agents manage CPU/mem/disk/port/etc.
112+
113+
---
114+
115+
This reference should guide Claude and collaborators to accurately reason about Coder’s internals and reflect the architecture correctly in user-facing documentation.

0 commit comments

Comments
 (0)