Getting Started: Guide for Engineers

Guide is a conversational AI agent that understands your organization's agent-aligned engineering standard. It helps you onboard, find growth areas, and interpret engineering artifacts against your skill markers.

Prerequisites

• Node.js 22+
• npm

Install

npm install @forwardimpact/guide

Install and configure

npx fit-codegen generate --all    # provided by @forwardimpact/libcodegen (a dependency of guide)
npx fit-guide --init

The fit-codegen step generates the gRPC service clients that Guide needs. If you skip it, imports fail with a missing module error.

The --init step generates:

• .env — service secrets (MCP_TOKEN) and port assignments
• config/config.json — service startup configuration

Configure credentials

Guide runs on the Anthropic API. Authenticate with one of these:

npx fit-guide --login     # OAuth PKCE flow (recommended)

Or set ANTHROPIC_API_KEY in .env manually. Guide validates credentials on startup and reports if they are missing.

Process data

Before you start the services, process the standard data into the indexes that Guide's services read at runtime:

npx fit-process resources # provided by @forwardimpact/librag
npx fit-process graphs    # provided by @forwardimpact/librag

These steps transform your data/pathway/ into the resource index, knowledge store, and graph index. Re-run them whenever you update standard data.

Start the service stack

npx fit-rc start          # provided by @forwardimpact/librc

The command supervises all required microservices (trace, vector, graph, pathway, map, mcp) in dependency order. fit-rc reads configuration and secrets automatically from .env. Stop the services with npx fit-rc stop.

Usage

npx fit-guide                                        # Start interactive conversation
npx fit-guide "What skills should I focus on for J060?"         # One-shot question
echo "What skills should I focus on for J060?" | npx fit-guide  # Equivalent piped form

Example pipe-mode output:

Level II engineers in your organization focus on three skill areas:

**System Design** — Design components that interact with other teams'
services, make technology choices within your domain, and document
architectural decisions.

**Technical Leadership** — Lead small cross-functional projects, unblock
peers on technical decisions, and mentor junior engineers on best
practices.

**Operational Awareness** — Own reliability for your services, set up
monitoring and alerting, and participate in incident response rotations.

Based on your current profile, prioritize System Design and Technical
Leadership to close the gap to Level II.

Guide reasons about your organization's specific skill definitions, behaviour expectations, and markers. It does not give generic career advice.

---

Troubleshooting

Configuration errors on startup

Guide validates configuration before it connects. If you see errors about missing ANTHROPIC_API_KEY or MCP_TOKEN, check that:

1. You ran npx fit-guide --init (creates .env with MCP_TOKEN)
2. You ran npx fit-guide --login or set ANTHROPIC_API_KEY in .env

Not authenticated error

Run npx fit-guide --login to authenticate with Anthropic, or set ANTHROPIC_API_KEY in .env.

Data not found

If Guide cannot answer questions, the knowledge indexes may be empty. Run the pipeline that processes the data:

npx fit-process resources
npx fit-process graphs

Then restart the services.

MCP endpoint unreachable

Verify the MCP service runs. Check npx fit-guide --status for health information, then restart the services:

npx fit-rc stop && npx fit-rc start

Missing module errors after install

Run code generation first. Guide depends on generated gRPC clients:

npx fit-codegen generate --all

Service startup failures

Check the logs for the service that fails:

npx fit-rc status                 # Identify the failing service
npx fit-rc logs <service>         # Print its current log (example: npx fit-rc logs trace)

Each microservice writes to data/logs/{service}/current. Common causes are an absent environment variable or a port conflict.

---

What's next