foglamp-local

Run with

python3 foglamp-local.py run scan.json

View a foglamp codebase scan with foglamp's real renderer, entirely on localhost — your scan data is embedded into a locally-served page and never uploaded; the only network egress is GETs for foglamp's public /_next renderer assets (everything else — /api favicons, analytics, RSC prefetch, all POSTs — is blocked and logged to .serve.log). Run python3 foglamp-local.py for an onboarding page with a copy-paste prompt, or paste the prompt below into an AI coding agent in your repo, then python3 foglamp-local.py run scan.json.

Scan prompt

Analyze THIS repository and write a foglamp "codebase scan" to scan.json — a map of how the
codebase works and how it uses AI. Produce ONLY the JSON below. Nothing is uploaded — a local
tool renders it on localhost, so your architecture never leaves your machine.

## Steps
1. Investigate the repo and build the JSON below. Write it to scan.json.
2. Then run:  python3 foglamp-local.py run scan.json   → opens http://localhost:8788/ with
   foglamp's real renderer, fully local.

## How to investigate
- Find where AI runs: generateText / streamText / generateObject / streamObject,
  @ai-sdk/* providers, agent loops, tool definitions (tool({...})).
- Identify the models and their provider (OpenAI, Anthropic, Google, …).
- Identify tools models can call (Exa, Firecrawl, Parallel, DB queries, internal
  functions) and external integrations/services.
- Map the business logic too: the internal services/pipelines the product is
  built from (billing, ingestion, background workers, domain services) — these
  become "service" nodes, and the interesting sentence goes on the edge
  (e.g. "charges Stripe on trial end").
- Map the main flows: entry points (routes, webhooks, pages, CLIs), scheduled jobs
  (crons/queues/workers), the agents, the models/tools they use, and the
  datastores/services they read and write.

## Output contract — write EXACTLY this shape to scan.json
{
  "version": 1,
  "project": {
    "name": "string (<=48)",
    "slug": "lowercase-dashed (<=48)",
    "tagline": "one line (<=80, optional)",
    "iconDomain": "favicon domain for the project, e.g. acme.com (optional)",
    "date": "YYYY-MM-DD"
  },
  "stats": { "agents": 0, "models": 0, "tools": 0, "integrations": 0 },
  "topModels":       [ { "id": "gpt-4o", "label": "GPT-4o", "domain": "openai.com" } ],
  "topTools":        [ { "id": "exa", "label": "Exa", "domain": "exa.ai" } ],
  "topIntegrations": [ { "id": "stripe", "label": "Stripe", "domain": "stripe.com" } ],
  "graph": {
    "nodes": [
      { "id": "chat", "label": "Dashboard chat", "kind": "entry", "sub": "/api/chat" },
      { "id": "agent", "label": "Support agent", "kind": "agent", "sub": "streamText",
        "sourceRef": "src/agents/support.ts:42",
        "detail": "Answers tickets with order lookups (<=200, optional)" },
      { "id": "gpt4o", "label": "GPT-4o", "kind": "model", "domain": "openai.com" },
      { "id": "billing", "label": "Billing service", "kind": "service",
        "sourceRef": "src/services/billing.ts" },
      { "id": "pg", "label": "Postgres", "kind": "store", "domain": "postgresql.org" }
    ],
    "edges": [
      { "from": "chat", "to": "agent", "kind": "triggers" },
      { "from": "agent", "to": "gpt4o", "kind": "calls" },
      { "from": "billing", "to": "pg", "kind": "writes", "label": "charges on trial end" }
    ]
  }
}

## Rules (these keep every scan consistent — do not break them)
- Caps: topModels <= 3, topTools <= 10, topIntegrations <= 10, graph.nodes <= 60,
  graph.edges <= 120. One map holds everything — AI flows AND business logic.
  Big maps are welcome (the viewer pans); aim for 20-40 nodes on a substantial
  codebase. Rich, not sparse — but every node must earn its place.
- Give every distinct agent its OWN node when there are <= 10 agents; only
  merge agents into one node when they are numerous and near-identical (then
  say so in sub, e.g. "12 near-identical scrapers"). Chain agents with
  agent->agent edges when one feeds the next.
- group (optional, <=24): tag related nodes with a shared group name — those
  nodes render as one labeled vertical stack. Group by feature/domain the way a
  team would say it ("Billing", "Ingestion", "Setup pipeline"), not by file
  layout. Use 2-3 groups of 3-6 nodes; leave hub-and-spoke nodes ungrouped.
- Node labels <= 28 chars, sub <= 40, edge labels <= 24.
- kind is one of: entry (trigger/route/page/CLI), cron (scheduled job), agent,
  model, tool, service (internal business-logic module/pipeline the project
  owns), store (DB/cache/index), external (3rd-party API).
- Edge kind (optional): "calls" | "reads" | "writes" | "triggers" — what the
  connection does. Prefer setting it; it's shown quietly (revealed when a flow
  is traced). Add a label only when a specific phrase says more (e.g. "charges
  on trial end" — put the business logic on edges); labels are always visible.
- domain is a favicon domain with no scheme (openai.com, anthropic.com, exa.ai,
  clickhouse.com). Add it to anything a recognizable company/product owns; omit it
  for purely internal nodes (entries, crons, services, internal tools). Use the
  product domain for models (gemini.google.com for Gemini, claude.ai for Claude).
- detail (optional, <=200) is shown when a node is clicked — one sentence of
  what it does. sourceRef (optional, <=120) is the repo path (plus :line) where
  the node lives, e.g. "src/agents/support.ts:42" — add it to internal nodes so
  teammates can jump to code.
- Every edge's from/to must reference an existing node id; ids unique.
- Use today's date for project.date.

Released under The Unlicense — public domain.