Handbook

For agents — Forge LCDL map

Compact reference when operating on this repo inside Cursor or other agent hosts.

Updated

Handbook IA (bookmark these)

Area Entry
Start Getting started · Adoption
Tutorials 101 · 201 · 301
Reference CLIENT-API · CONTRACT-SPEC · SCHEMAS
Enterprise Enterprise hub
Contribute Docs authoring · Website publishing

Risk-aware edits: Safe edit matrix.

Roles and layers

Role Responsibility Entry docs
Consumer Playwright/runtime, run_task, env profiles ADOPTION.md, PLAYWRIGHT-DISCOVERY.md
Task author Contract Markdown + optional contract.json CONTRACT-SPEC.md, SCHEMAS.md
Maintainer Tasks under src/forge_lcdl/tasks/, registry catalog_v1.py, TASK_REGISTRY_V1
Benchmark operator forge_lcdl.benchmarks BENCHMARKS.md

LCDL does not own Fleet jobs, Docker, or your browser installer—only library calls.

Stable entrypoints (Python)

  • forge_lcdl.run_task, TaskRunner, read_certificator_profile, contracts_root — README.md
  • forge_lcdl.contracts_api.load_contract_spec, validate_contract_* — metadata and shallow schema checks (CONTRACT-SPEC.md)
  • forge_lcdl.generic — transport + JSON quirks
  • forge_lcdl.operators — seq, until_ok, fallback_chain, etc.
  • forge_lcdl.execution — LcdlClient, ExecutionEngine

Contracts layout

Bundled Markdown: src/forge_lcdl/contracts/<task_id>/v1/contract.md

Machine-readable optional sidecar: contract.json (ContractSpec v2 fields + unknown keys folded into ContractSpec.extensions).

Verification commands (typical patch)

python -m compileall -q src tests
pytest -q
python3 scripts/audit_contract_docs.py

Focused:

pytest -q tests/test_contracts_api.py tests/test_page_mechanics_schema.py tests/test_catalog_tasks.py

Cursor helper: .cursor/skills/lcdl-implement/scripts/run_lcdl_checks.py

Live Granite (optional): pytest -m granite (README.md).

Cursor assets

Asset Location
Rules .cursor/rules/lcdl-*.mdc
Skills .cursor/skills/lcdl-*/SKILL.md (/lcdl-implement, /lcdl-debug, …)
Agents .cursor/agents/*.md
MCP sidecar example .cursor/mcp.json.example

MCP

Direction Doc
Python → MCP servers MCP-CLIENT.md
Cursor → LCDL tools MCP-SIDECAR.md

Task packs and graph

Publication

Handbook submodule + forge-lcdl-website build — WEBSITE-PUBLISHING.md

External ecosystem

Resource Notes
Forge Blueprints handbook Methodology / process framing
Forge SDLC product site Narrative landing
lcdl-snippets Sibling demos — README § Demo repos