oaustegard/mapping-webapp

Mapping Webapp

Generate _FEATURES.md files documenting what a web app does — screens, flows, states, behavioral invariants. Companion to mapping-codebases which documents code structure.

v0.3.0: Code-first architecture. The code IS the ground truth; screenshots are supplementary verification.

Prerequisites

1. mapping-codebases must have run first (_MAP.md files exist)
2. Claude API key available (via api-credentials skill or ANTHROPIC_API_KEY env var)
3. Optional: webctl for visual verification (not required for --code-only)

Usage

# Code-only analysis (no browser needed):
python /mnt/skills/user/mapping-webapp/scripts/featuremap.py \
  --app-url https://example.com --codebase /path/to/repo --code-only

# Full pipeline (code analysis + selective visual verification):
python /mnt/skills/user/mapping-webapp/scripts/featuremap.py \
  --app-url https://example.com --codebase /path/to/repo

# Incremental update:
python /mnt/skills/user/mapping-webapp/scripts/featuremap.py \
  --app-url https://example.com --codebase . --incremental

Options

| Flag | Default | Description | |------|---------|-------------| | --app-url | required | Base URL of the web app | | --codebase | required | Path to repo root (must have _MAP.md files) | | --output | <codebase>/_FEATURES.md | Output path | | --max-pages | 100 | Cap on pages to discover | | --code-only | false | Skip all vision — code analysis only | | --verify-only | false | Only run vision on already-analyzed pages | | --batch-size | auto | Pages per batch (auto-detected from environment) | | --incremental | false | Only re-process changed pages | | --viewport | 1280x720 | Screenshot viewport (WxH) | | --routes | none | Comma-separated routes or path to routes file | | --screenshots-dir | <codebase>/screenshots | Where to store PNGs | | --model | claude-sonnet-4-6 | Claude model for analysis/vision | | --dry-run / -n | false | Discover only, print sitemap |

Architecture: Code-First Pipeline

Phase 1: DISCOVER

Discovers pages from code structure, not browser crawling:

• Scans for HTML files (static sites)
• Detects framework routing conventions (Next.js, SvelteKit, etc.)
• Parses _MAP.md for page references
• Supplements with --routes for manual seeding

No browser required for discovery.

Phase 2: ANALYZE

Reads source code for each discovered page and uses Claude API (text, not vision) to generate behavioral descriptions:

• Finds relevant source files (HTML + referenced JS/CSS)
• Includes _MAP.md excerpts for code context
• Produces: what the user sees, interactions, invariants, code references

Code-derived descriptions are usable standalone. Vision is enrichment, not requirement.

Phase 3: VERIFY (optional)

Selective visual verification for pages where it adds value:

• Skips error pages (404, 500), gated pages, redirects
• Captures screenshots + accessibility trees via webctl
• Sends to Claude vision API to verify/enrich code descriptions
• Falls back to code description if vision fails

Skipped entirely with --code-only. Run only this phase with --verify-only.

Phase 4: ASSEMBLE

Compiles all descriptions into _FEATURES.md:

• Source badges indicate code-analyzed vs visually-verified
• Screenshot references only for verified pages
• Status summary with breakdown by source

Environment-Adaptive Batching

The skill auto-detects the runtime environment and adjusts batch size:

| Environment | Batch Size | Notes | |-------------|-----------|-------| | Claude.ai container | 4 pages | Short bash timeouts | | Claude Code on Web | 12 pages | Longer execution windows | | Local CLI | Unbatched | Full control |

Override with --batch-size N.

Progress is checkpointed after each batch via _FEATURES_MANIFEST.json, so work survives if a conversation ends mid-pipeline.

Incremental Mode

Each run stores page hashes and descriptions in _FEATURES_MANIFEST.json. With --incremental:

• Code analysis: skips pages with existing descriptions
• Visual verification: skips pages with unchanged screenshots
• Descriptions from previous runs are preserved and merged

Auth / Gated Pages

Pages requiring authentication are detected during verification (redirect detection + text heuristics) and marked GATED. The skill generates step-by-step manual capture instructions in GATED_PAGES.md.

Output Format

# _FEATURES.md — App Name
Generated: 2026-03-22T12:00:00+0000
App URL: https://example.com

## Feature Inventory

### Status Summary
- **Documented:** 45 pages
  - Code-analyzed: 40
  - Visually verified: 5
- **Gated (auth required):** 2 pages

### Page Title (`/route`)
> *Derived from source code analysis*

**What the user sees:** Prose description from code analysis.

**Interactions:**
- Button "X" → does Y

**Invariants:**
- Rule 1

**Code:** `src/page.html` :1

---

Relationship to CLAUDE.md

_FEATURES.md is the behavioral source of truth. Combined with _MAP.md (structural):

1. mapping-codebases → _MAP.md (structural)
2. mapping-webapp → _FEATURES.md (behavioral)
3. Merge both into CLAUDE.md architecture/concepts sections

Limitations

• Code analysis requires Claude API calls (tokens)
• Visual verification requires webctl + a running app instance
• SPAs with client-side routing may need --routes flag
• Auth-gated pages require human intervention for visual verification
• Code analysis quality depends on source code readability