> ## Documentation Index
> Fetch the complete documentation index at: https://docs.livepeer.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Contributor Tools

> Contributor-facing tools for setup, local preview, validation, hooks, editor support, scoped docs profiles, and governed page movement.

# Contributor Tools

Contributor tools should make the correct workflow the easiest workflow: setup, preview, validate, repair, and move pages through repo-backed commands rather than private maintainer knowledge.

## Primary Tools

| Tool                     | Path                       | Purpose                                                                                                                    |
| ------------------------ | -------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `lpd` CLI                | `tools/lpd`                | Unified command surface for setup, doctor, dev server, tests, hooks, scripts, repair, AI sitemap, and governed page moves. |
| Git hooks                | `.githooks/`               | Local staged checks, no-deletion checks, pre-push task contracts, browser verification helpers.                            |
| Scoped preview tooling   | `tools/dev/preview/`       | Mintlify launchers, scoped docs config generation, watcher patches, custom loader.                                         |
| Authoring helpers        | `tools/dev/authoring/`     | Local MDX formatting and callout helpers.                                                                                  |
| Editor extensions        | `tools/editor-extensions/` | VS Code extensions for authoring tools, component picker, MDX preview, markdown list helpers.                              |
| VS Code workspace config | `.vscode/`                 | Recommended extensions, settings, tasks, snippets, MCP config.                                                             |
| Repo libraries           | `tools/lib/`               | Shared JS modules used by validators, generators, hooks, and governance scripts.                                           |

## `lpd` Workflows

| Workflow                        | Command                                                                                                                                                                                                                              |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| First-time setup                | `bash tools/lpd setup --yes`                                                                                                                                                                                                         |
| Environment check               | `PATH="/opt/homebrew/bin:$PATH" bash tools/lpd doctor --strict` when Homebrew Node is not on shell PATH                                                                                                                              |
| Start docs locally              | `lpd dev -- --port <non-reserved-port>`                                                                                                                                                                                              |
| Scoped docs preview             | `lpd dev --scoped --scope-version v2 --scope-language en --scope-prefix v2/orchestrators`                                                                                                                                            |
| Staged validation               | `lpd test --staged`                                                                                                                                                                                                                  |
| CI-like local validation        | `lpd ci --skip-browser`                                                                                                                                                                                                              |
| Generate AI sitemap             | `lpd ai-sitemap --write`                                                                                                                                                                                                             |
| Move a page                     | `lpd move-page <old> <new> --check` then rerun without `--check` after review                                                                                                                                                        |
| Repair a governed surface       | `lpd repair --surface <id> --staged --write`                                                                                                                                                                                         |
| Fetch live social feeds locally | `node operations/scripts/dispatch/content/data/run-solutions-social-fetch.js [--mode forum,youtube] [--dry-run] [--skip discord]` (loads `.env`; mirrors `dispatch-social-feeds.yml` for workstation use; **local-only, not in CI**) |

## Environment Notes

The non-interactive Codex shell used for this audit did not include `/opt/homebrew/bin` on `PATH`, so `node`, `npm`, and `mintlify` were initially hidden. Discovery found:

* Homebrew Node: `/opt/homebrew/bin/node`, version `v22.22.2`
* NVM Node: `~/.nvm/versions/node/v22.22.1/bin/node`
* Mintlify: `/opt/homebrew/bin/mintlify`, version `4.2.446`
* `lpd doctor` passes when `/opt/homebrew/bin` is added to `PATH`

Do not report required tools as unavailable until checking version managers, repo wrappers, setup docs, and common install paths.

## Editor Tooling

| Surface                               | Use                                                                       |
| ------------------------------------- | ------------------------------------------------------------------------- |
| `.vscode/extensions.json`             | Recommended local extensions.                                             |
| `.vscode/settings.json`               | Workspace settings.                                                       |
| `.vscode/tasks.json`                  | Repeatable editor tasks.                                                  |
| `.vscode/mcp.json`                    | MCP server configuration for in-IDE agent access.                         |
| `.vscode/components.code-snippets`    | Component snippets.                                                       |
| `.vscode/templates.code-snippets`     | Template snippets.                                                        |
| `.vscode/mdx.code-snippets`           | MDX authoring helpers.                                                    |
| `.vscode/mintlify.code-snippets`      | Mintlify built-in component snippets.                                     |
| `.vscode/lp-components.code-snippets` | Legacy component aliases.                                                 |
| `tools/editor-extensions/install.sh`  | Installs local VS Code extensions and verifies packaged extension parity. |

## VS Code Snippets

Workspace snippets in `.vscode/*.code-snippets` are available to any contributor opening this repo. Five files cover the full authoring surface; all component-driven snippets are generator-emitted from `docs-guide/config/component-registry.json` via `operations/scripts/generators/components/library/generate-ui-templates.js`.

| File                                  | Snippets | Scope                                                                     |
| ------------------------------------- | -------- | ------------------------------------------------------------------------- |
| `.vscode/mdx.code-snippets`           | 23       | Frontmatter blocks, page scaffolds, reusable MDX patterns                 |
| `.vscode/mintlify.code-snippets`      | 25       | Mintlify built-in components (`Card`, `Tabs`, `Steps`, `Accordion`, etc.) |
| `.vscode/components.code-snippets`    | 113      | Custom Livepeer components                                                |
| `.vscode/lp-components.code-snippets` | 125      | Legacy component aliases retained for backward compatibility              |
| `.vscode/templates.code-snippets`     | 26       | Full page templates by page type                                          |

JSX tag snippets accept both bare names (`Card`) and opening-tag prefixes (`<Card`), so they expand cleanly when typed after an angle bracket. The frontmatter snippet auto-fills today's date for `lastVerified` and offers dropdowns for `audience`, `pageType`, `status`, and `purpose` aligned to the canonical enums.

Regenerate after registry changes:

```bash theme={"theme":{"light":"github-light","dark":"dark-plus"}}
node operations/scripts/generators/components/library/generate-ui-templates.js --write
```

Counts above are verified against live snippet files. The earlier per-page reference at `docs-guide/tooling/dev-tools.mdx` is retired and redirects here.

## Contributor Safety Rules

* Install hooks before substantial work: `bash .githooks/install.sh`.
* Do not use `--no-verify` unless explicitly authorized by a human override policy.
* Do not edit `.allowlist` casually; human commits require the `allowlist-edit=true` trailer.
* Do not delete tracked files without the governed deletion approval path.
* Do not use port `3000` for direct Mintlify preview or port `3333` via `lpd dev` in agent sessions.
* Do not switch branches in the existing worktree.

## Tooling Gaps

| Gap                                                | Evidence                                                                                                                        | Required action                                                                                 |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| PATH assumptions still leak into commands          | `lpd doctor` warned until `/opt/homebrew/bin` was loaded.                                                                       | Update tooling docs to show PATH discovery/remediation for non-interactive shells.              |
| Backup artifacts are tracked                       | `.vscode/livepeer-legacy.code-snippets.bak` and workspace `.bak` files are present.                                             | Classify as compatibility aliases or remove through governed deletion.                          |
| Tool catalogs can drift                            | `tools/script-index.md` contains legacy-looking script paths.                                                                   | Regenerate script indexes and verify generated catalogs.                                        |
| Node module directories exist under governed roots | `tools/node_modules/` and `operations/tests/node_modules/` are installed dependencies and intentionally ignored by most audits. | Keep selection helpers excluding `node_modules`; do not include them in reports or docs counts. |

## Related

* `docs-guide/tooling/lpd-cli.mdx`
* `docs-guide/tooling/lpd-mdx-preview.mdx`
* `docs-guide/contributing/contributing.mdx`
* `docs-guide/contributing/local-preview.mdx`
* `docs-guide/contributing/git-hooks.mdx`
* `.githooks/README.md`