Add: AGENTS.md documenting repo structure for AI agents (Closes #1978)

[Vamshi1404]

Description

Fixes #1978

Adds an AGENTS.md file at the repo root documenting Lumen's structure for AI coding agents, following the open agents.md convention. Covers repo/package layout, key entry points, dev environment setup, testing, linting, code conventions, and PR/commit conventions — scoped to Lumen as a generalized agent framework rather than any single workflow, per the issue's request.

Verified manually against the local repo:

• All file paths under "Key entry points" exist at the stated locations (lumen/dashboard.py, lumen/pipeline.py, lumen/ai/ui.py, lumen/ai/llm.py, lumen/ai/agents/base.py, lumen/ai/coordinator/base.py, lumen/sources/base.py, lumen/transforms/base.py, lumen/views/base.py)
• Repo structure tree matches actual top-level layout (docs/, examples/ confirmed present)
• Setup/test/lint commands copied verbatim from CONTRIBUTING.md and pixi.toml, not invented

No code changes — documentation only, no tests apply.

AI Disclosure

Tool & Model: OpenCode + big-pickle
Usage: Used to draft AGENTS.md content, explore repo structure, and verify file paths and commands against the real repo before committing.

• I have tested all AI-generated content in my PR.
• I take responsibility for all AI-generated content in my PR.

Checklist

• Tests added and are passing (N/A — docs-only change)
• Added documentation

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 75.24%. Comparing base (ef07729) to head (7295e2a).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2036   +/-   ##
=======================================
  Coverage   75.24%   75.24%           
=======================================
  Files         212      212           
  Lines       39182    39182           
=======================================
  Hits        29484    29484           
  Misses       9698     9698           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[ghostiee-11]

nice, thanks for picking this up. main thing I'd push on: a lot of this already lives in docs/contributing.md and lumen/ai/prompts/GUIDANCE.md, so we'd be maintaining a third copy that quietly drifts. could we link to those and keep AGENTS.md for the stuff that isn't written down anywhere yet?

also the one thing an AI agent most needs is missing: https://holoviz.org/contribute.html#ai-readme and the AI Disclosure section in the PR template.

[ahuang11]

Thanks for starting this! I think right now, there are directories that the LLM should definitely prioritize, while others not so much, which comes from experience developing Lumen, so I think I'll create a separate PR on top of this one!