---
id: faq
title: FAQ
sidebar_position: 3
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Use this FAQ when onboarding teammates. It highlights answers that commonly come up while running BlackRoad OS locally or in shared environments.

## How do I install dependencies?

- Use Node 20+ and `npm install` from this repo to pull docs dependencies.
- Development repos such as `blackroad-os-core` and `blackroad-os-operator` also target Node 20+. Install Docker and Terraform if you plan to run infra workflows.

## Which repo do I run first?

1. Start the Operator runtime so agents can register and emit events.
2. Launch `blackroad-os-api` to expose metrics and task orchestration endpoints.
3. Bring up Prism Console for observability.
4. Optionally start packs (Finance, Education) to exercise specific playbooks.

## Where do configuration values live?

Most services load environment variables from `.env` files. Secrets should be managed through your vault of choice; do **not** check them into Git. Docs-specific settings (Algolia, API sources) are read from `process.env` during build.

## How do I add a new document?

Place the MDX file under the relevant top-level folder (Getting Started, Platform Guides, Packs, Reference, Governance & Policy). The sidebar is autogenerated from directories, so the file will appear automatically.

## What if I hit a broken link?

The docs CI workflow fails the build on broken links. Run `yarn build` locally to surface issues before pushing.

## How are agents documented?

Agent pages are generated from `agent-catalog/agents.yaml` during the build. Update that file and rerun `yarn build` (or `yarn build:catalog`) to regenerate docs.

## Is there a dark/light mode toggle?

Yes. The site defaults to dark mode but offers a toggle in the header if you prefer light mode.

<Tabs>
  <TabItem value="resources" label="Fast references">
    - Platform: `/platform/core/overview`
    - Operator runtime: `/platform/operator/runtime`
    - Prism Console: `/platform/prism-console/overview`
  </TabItem>
  <TabItem value="support" label="Need help?">
    - Open an issue in `blackroad-os-docs` for docs-specific problems.
    - Use the operator pager channel for runtime incidents.
  </TabItem>
</Tabs>