Create documentation site for pi-processes extension

[aliou]

Note

This issue was opened by pi (synthetic/hf:zai-org/GLM-5)

Overview

Create a documentation site for the pi-processes extension, built on GitHub Pages at aliou.github.io/pi-processes/. The site will be markdown-based with videos embedded directly.

Docs pages (one per feature)

File	Content
docs/index.md	Landing: what it does, hero video, install snippet, links to feature pages
docs/installation.md	npm + git install, quick first use
docs/process-panel.md	/ps command: what it shows, keybindings, workflow example, video
docs/logs.md	/ps:logs: log overlay, search, stream filter, keybindings, video
docs/pin.md	/ps:pin: pin dock to a process, picker behavior, video
docs/dock.md	/ps:dock: show/hide/toggle, dock states, compact monitoring, video
docs/kill.md	/ps:kill: terminate a process, picker behavior
docs/clear.md	/ps:clear: remove finished processes
docs/settings.md	/ps:settings: all setting categories, recommended defaults, video
docs/tool-reference.md	LLM-facing process tool: all 7 actions, example JSON payloads, alert flags
docs/log-watches.md	logWatches on start: pattern/stream/repeat fields, examples
docs/troubleshooting.md	Common issues and fixes
docs/platform-support.md	macOS/Linux yes, Windows no

Content template per page

Each feature page follows a consistent structure:

• Title + one-line summary
• When to use it
• Syntax / usage
• Keybindings (if applicable)
• Video embed (using ![](VIDEO_URL))
• Related pages

Site generator: VitePress

Use VitePress for:

• Markdown-first, multi-page by default
• Sidebar, TOC, dark/light mode, code highlighting built in
• Clean GitHub Pages deployment

Structure

docs/
  .vitepress/
    config.ts          # sidebar, nav, title, theme
    theme/
      custom.css       # match previous design (Satoshi font, spacing, etc.)
  index.md
  installation.md
  process-panel.md
  logs.md
  pin.md
  dock.md
  kill.md
  clear.md
  settings.md
  tool-reference.md
  log-watches.md
  troubleshooting.md
  platform-support.md

Navigation config

Overview         → index.md
Installation     → installation.md
Commands
  /ps            → process-panel.md
  /ps:logs       → logs.md
  /ps:pin        → pin.md
  /ps:dock       → dock.md
  /ps:kill       → kill.md
  /ps:clear      → clear.md
  /ps:settings   → settings.md
Reference
  process tool   → tool-reference.md
  logWatches     → log-watches.md
Help
  Troubleshooting → troubleshooting.md
  Platform support → platform-support.md

GitHub Pages workflow

New file: .github/workflows/docs.yml

• Trigger: push to main when docs/** or README.md changes, plus workflow_dispatch
• Steps: install deps, build VitePress, deploy via actions/deploy-pages
• URL: aliou.github.io/pi-processes/

Separate from publish workflow. Docs reflect latest main, not npm release cadence.

Other updates

Area	Change
package.json files	Do not add docs/. Keep current: src, skills, README.md, CONTRIBUTING.md
package.json scripts	Add docs:dev, docs:build, docs:preview
package.json devDependencies	Add vitepress
skills/pi-processes/SKILL.md	Add "Reference" note with docs URL: https://aliou.github.io/pi-processes/
README.md	Remove VIDEO HTML comments. Add docs site link near the top.
CONTRIBUTING.md	Update "Docs page build" section to reflect VitePress approach
.github/docs-site/	Remove (previous attempt artifacts)
.gitignore	Add docs/.vitepress/dist, docs/.vitepress/cache
AGENTS.md	Add note to update docs and prompt for new videos when features change

AGENTS.md addition

Add a documentation section to AGENTS.md:

## Documentation

When modifying user-facing features (commands, settings, tool actions):

1. Update the corresponding `docs/*.md` page.
2. If the feature has a video and the change affects usage, prompt the user:
   > "This change affects the {feature} video. Should we re-record it?"
3. New features with UI should have a video. Prompt the user to record one.

Checklist

• Add VitePress to devDependencies
• Create docs/.vitepress/config.ts with sidebar/nav config
• Create docs/.vitepress/theme/custom.css matching previous design
• Create all docs pages listed above
• Add root scripts: docs:dev, docs:build, docs:preview
• Add .github/workflows/docs.yml for GitHub Pages deployment
• Update CONTRIBUTING.md with new docs build section
• Remove .github/docs-site/ directory
• Remove VIDEO comments from README.md
• Add docs URL to README and skill
• Update .gitignore for VitePress build artifacts
• Add documentation section to AGENTS.md

[aliou]

Videos to create

Video ID	Feature page	Description
agent-starts-processes	index.md, tool-reference.md	Pi starts a long-running process and keeps working
process-panel	process-panel.md	Browse and manage processes from the panel
inspect-logs	logs.md	Open the log overlay and inspect output
pin-process	pin.md	Pin the dock to one process
dock-control	dock.md	Show, hide, and use the dock
settings	settings.md	Adjust process extension settings

Video recording guidelines

• Keep each video under 30 seconds
• Focus on one feature per video
• Show the command being typed and the result
• Use a clean demo project (e.g., Northwind API pattern from CONTRIBUTING.md)
• Record at 1080p, export as MP4