Getting Started: Landmark for Leaders

Landmark surfaces engineering-system signals from Map's activity layer — organization roster, GitHub artifact evidence assessed by Guide against your standard's markers, GetDX snapshot outcomes, and engineer voice comments — so you can see what the data says about how engineering is functioning.

Landmark requires Map's activity layer (Supabase). If you haven't set it up, see Getting Started: Map for Leaders first. To explore with synthetic data, see Trying the activity layer with synthetic data in the Map guide.

Prerequisites

• Node.js 22+
• npm
• Map's activity layer running and populated
• A Landmark session created with fit-landmark login — see Authentication below

Install

npm install @forwardimpact/landmark

Authentication

Every Landmark command except marker resolves the caller's identity from a Supabase Auth session. Row-level security uses the JWT's email claim to scope every query, so the session both authenticates you and determines what you can see.

There is no hosted Forward Impact service and no free tier. Landmark reads from the Supabase project you stand up via Map.

Today's minimum stand-up is three steps under Map plus one Landmark login:

1. Start the activity layer. npx fit-map activity start brings the Supabase stack up and prints a one-line ready confirmation. The bootstrap recipe (just env-setup for monorepo contributors) writes SUPABASE_URL, SUPABASE_ANON_KEY, JWT_SECRET, and SUPABASE_SERVICE_ROLE_KEY to .env. Hosted Supabase users copy the same four values from Project Settings → API.

2. Push the roster. npx fit-map people push ./people.yaml populates activity.organization_people.

3. Provision auth users. npx fit-map people provision reconciles auth.users against the roster so each engineer's email maps to an authenticable identity. See Provision Engineer Auth Users for the operator workflow.

4. Sign in. npx fit-landmark login walks Supabase's magic-link flow, captures the session at a localhost callback, and stores it (0600) in your platform's config directory — ~/.config/landmark/credentials.json on Linux; see Sign In to Landmark for the macOS and Windows paths. Subsequent commands resolve identity automatically. Use --otp to skip the browser and paste the six-digit code instead:

   npx fit-landmark login --email you@example.com
   npx fit-landmark login --email you@example.com --otp
   

   For unattended agents and service accounts that cannot run an interactive flow, an operator issues a signed JWT with fit-map auth issue instead — see Issue Service-Account Tokens and Sign In to Landmark for the full flows.

Once you are signed in, every command in the rest of this guide works against your scope. fit-landmark logout deletes the local credentials file when you need to switch identity or revoke the session locally.

For more on what data the session unlocks visibility into, see List Engineering Data Sources.

View the organization

See who is in the organization and how teams are structured:

npx fit-landmark org show
npx fit-landmark org team --manager alice@example.com

org show prints the full organization directory — names, roles, and reporting lines. org team walks the hierarchy under a specific manager, which is the scope most other commands operate on.

Browse marker definitions

Look up the observable indicators defined for any skill in your agent-aligned engineering standard:

npx fit-landmark marker task_completion
npx fit-landmark marker task_completion --level working

This is a reference view — it reads directly from your standard YAML and does not require Supabase. Use it to review what markers exist before checking evidence against them.

View practice patterns

See aggregate marker evidence across a team scope:

npx fit-landmark practice --manager alice@example.com
npx fit-landmark practice --skill system_design --manager alice@example.com

Practice patterns show where your team has strong evidence of skill practice and where evidence is thin — helping you identify coaching opportunities before they become gaps.

How evidence gets populated

Landmark presents evidence — it doesn't create it. Evidence rows come from two producers. Map's transform pipeline derives a first layer directly from ingested GitHub artifacts (it runs automatically during npx fit-map activity transform). Guide's evaluation pipeline goes deeper: it reads the same artifacts from Map, evaluates each one against the markers in your engineering standard, and writes its assessments back as evidence rows. In production the Guide pass runs on a schedule (a cron job or GitHub Action) so evidence stays current as new artifacts arrive:

echo "evaluate unscored artifacts for all" | npx fit-guide

You do not need to run this manually in most setups — your operations team configures it once during Guide setup.

Browse evidence

Drill into the evidence rows linked to agent-aligned engineering standard markers:

npx fit-landmark evidence --email bob@example.com
npx fit-landmark evidence --skill system_design --email bob@example.com

Each row shows the artifact, the marker it was matched to, the skill and proficiency level, and Guide's rationale for the match. Filter by --skill to focus on a specific area or omit it to see everything.

Track snapshot trends

GetDX snapshots capture quarterly survey results. Landmark reads them from the activity layer:

npx fit-landmark snapshot list
npx fit-landmark snapshot show --snapshot MjUyNbaY
npx fit-landmark snapshot show --snapshot MjUyNbaY --manager alice@example.com

snapshot list shows available snapshots. snapshot show displays factor and driver scores — add --manager to scope to a single team.

Track a specific driver or factor over time:

npx fit-landmark snapshot trend --item MTQ2 --manager alice@example.com

Compare a snapshot against organizational benchmarks:

npx fit-landmark snapshot compare --snapshot MjUyNbaY --manager alice@example.com

Check promotion readiness

See which next-level markers an engineer has already evidenced and which are still outstanding — a checklist for promotion conversations:

npx fit-landmark readiness --email bob@example.com
npx fit-landmark readiness --email bob@example.com --target J060

Without --target, readiness uses the next level above the engineer's current level. With --target, you can check against any specific level.

View individual timelines

Track how an engineer's evidence has accumulated over time, aggregated by quarter:

npx fit-landmark timeline --email bob@example.com
npx fit-landmark timeline --email bob@example.com --skill system_design

Timelines help you see whether growth is accelerating, stalling, or concentrated in one area. Add --skill to focus on a specific capability.

View evidence coverage

See how complete an individual's evidence coverage is across their expected skills:

npx fit-landmark coverage --email bob@example.com

Coverage shows evidenced artifacts versus total expected markers — a quick gauge of how well the evidence record reflects what the engineer actually does.

Compare evidenced vs derived capability

See where real practice diverges from what the agent-aligned engineering standard predicts:

npx fit-landmark practiced --manager alice@example.com

This compares the capability the team should have (based on their job profiles) against what marker evidence actually shows. Skills with high derived capability but low evidence may indicate either a data gap or a coaching opportunity.

View team health

The health view is Landmark's centerpiece — it joins driver scores, contributing skill evidence, engineer voice comments, and (when Summit is installed) growth recommendations into a single picture:

npx fit-landmark health --manager alice@example.com
npx fit-landmark health --manager alice@example.com --verbose

Default output is a compact table — one row per driver with the GetDX percentile, the vs_org anchor, and a More cell hinting how many additional percentile anchors are available. A deduped Recommendations trailer follows. Pass --verbose for the full per-driver paragraph layout: every percentile anchor (vs_prev, vs_org, vs_50th, vs_75th, vs_90th), contributing skills, evidence counts, GetDX comments, and growth recommendations.

Sample default output:

  Team — health view

  Drivers (6)
  ────────────────────────────────────────────────────────────
  #  Driver          Percentile  vs_org   More
  1  Quality         42nd        -10      +4 anchors via --verbose
  2  Reliability     n/a         n/a      -
  …

Surface engineer voice

Landmark surfaces GetDX snapshot comments so you can hear what engineers are saying:

npx fit-landmark voice --manager alice@example.com

  alice@example.com team — engineer voice

    Most discussed themes:
      incident              8 comments   "On-call handoffs are still rough", "Runbook coverage is improving"
      onboarding            3 comments   "New hire ramp-up is smoother this quarter"
      deploy                2 comments   "Release cadence feels more predictable now"

    Aligned with health signals:
      Codebase Experience driver (48.6th pctl)
      Requirements Quality driver (49.8th pctl)

In manager mode, comments are bucketed by theme and aligned to low-scoring drivers — showing where engineer sentiment matches the data. In individual mode (--email), comments appear as a timeline alongside evidence context.

Output formats

All Landmark commands support --format text|json|markdown. The default is text (formatted for the terminal). Use json for programmatic consumption or markdown for sharing in documents and pull requests.

---

What's next