(onboarding): repository environment discovery and assisted configuration generation

[krokoko]

Component

Documentation

Describe the feature

Provide an optional onboarding flow—CLI command, one-shot agent task, or deterministic static analyzer—that inspects a GitHub repository and produces suggested environment configuration: Dockerfile fragments, Dev Container starter files, install/build/test commands, and Blueprint-ready hints derived from existing repo signals (CI workflows, package manifests, CONTRIBUTING.md, .tool-versions, mise.toml, etc.).

Output is advisory: operators review and commit the generated files; the platform does not silently mutate customer repos. This complements the platform default image and per-repo overrides defined in the repo-defined environments feature—it lowers the barrier from "default works poorly" to "repo has a checked-in spec" without manual Dockerfile authoring.

Use case

I'm always frustrated when onboarding a new repo to ABCA requires guessing which Node version, system packages, or setup commands the agent needs. Repo owners often already encode this in GitHub Actions and READMEs but not in a form the compute layer consumes. An assisted scan would bootstrap devcontainer.json, Dockerfile additions, or Blueprint documentation snippets so the first real task succeeds without trial-and-error submissions.

Proposed solution

1. Signal inventory — Define a fixed set of inputs the scanner reads (non-exhaustive): .github/workflows/*, package.json, pyproject.toml, go.mod, mise.toml, .nvmrc, Dockerfile*, existing devcontainer.json, AGENTS.md, CI install/build/test steps.
2. Deterministic pass (phase 1) — Pure TypeScript or Python module that emits a structured report: detected languages, inferred versions, suggested base image family, recommended postCreateCommand / test command, gaps vs platform default image. No LLM required for v1.
3. Assisted pass (phase 2, optional) — Repo-less or repo-backed workflow (knowledge/* or dedicated onboarding workflow) that drafts devcontainer.json and a short operator checklist from the inventory + platform docs. Human approves before merge.
4. CLI entrypoint — bgagent repo analyze --repo owner/name [--output dir] writes suggestions to stdout or a local directory (not auto-committed to the customer repo).
5. Blueprint hook (phase 2) — Optional flag on Blueprint deploy: run analyzer once, surface warnings in deploy output if repo lacks manifest and default image likely insufficient (e.g. Rust repo detected, no cargo in default image).
6. Docs — Onboarding guide section: "Start with default → analyze → commit spec → enable override."

Acceptance criteria

• Documented CLI or script produces a structured analysis report for at least three fixture repo profiles (Node monorepo, Python uv, polyglot with CI).
• Report includes actionable suggestions (base image family, install commands, test command, manifest file drafts or diffs).
• No automatic writes to the target GitHub repo without explicit operator action.
• Operator guide explains relationship to platform default image and Blueprint compute.image overrides.
• Tests cover the deterministic analyzer against fixture repositories.

Other information

• Depends on / pairs with: repo-defined environments issue (default + override hierarchy must exist before generated specs are consumed at runtime).
• Related roadmap: Dynamic onboarding artifacts (broader context attachments; this issue is narrowly scoped to environment/toolchain discovery).
• Related design: docs/design/REPO_ONBOARDING.md, docs/design/COMPUTE.md.
• Deliberately separate from runtime image build: analysis can ship first as DX-only; image resolution ships in the sibling feature.
• Alternatives considered: manual docs only (slow adoption); mandatory manifest at onboarding (too high a bar for first task).

Acknowledgements

• I may be able to implement this feature
• This might be a breaking change

[krokoko]

Pairs with #387 (repo-defined environments): analysis output feeds the default → override → repo-manifest hierarchy defined there.