---
kind: epic
slug: repo-discovery-onboarding
title: Repository discovery, context import, and agent onboarding
plan_slug: automation-foundation
status: ready
priority: P1
tenant_id: global
cursor_epic_id: null
updated_at: "2026-09-25"
---

# Epic objective

Replace one-repository-at-a-time URL entry with a secure account/instance flow: discover repositories visible to the current operator, explicitly select repositories for the current workspace, import bounded repository context, and show accurate agent setup instructions.

## Product decisions

- Repositories are attached to the current workspace; discovery does not implicitly create workspaces.
- GitHub uses the current user's linked Auth.js account. Access tokens remain server-side and users explicitly re-authorize when additional scope is required.
- Forgejo/Gitea v1 uses an instance URL and a server-side token environment-variable reference. Plaintext PATs are not persisted in the application database.
- Batch connection and context ingestion are separate operations. Connecting repos is fast and atomic; remote content import is retryable and reports per-repo progress.
- V1 context import is bounded to root `README.md`, `AGENTS.md`, `CONTRIBUTING.md`, and `.convoys/*.md`. Recursive `docs/**` and `plans/**` import is deferred until source identity and conflict semantics are specified.
- Agent setup instructions must match a transport the MCP server actually supports and must never expose `DATABASE_URL`, forge tokens, or provider API keys.

## In scope

- Paginated GitHub and Forgejo/Gitea repository discovery with normalized, zod-validated results.
- Searchable multi-select picker and admin-only, idempotent batch connection.
- Idempotent import of supported docs as `document` objects and existing convoy manifests with source provenance.
- OpenCode and Cursor onboarding guidance for the deployed MCP transport.
- Optional bootstrap PR only when branch/file commit support exists; otherwise a separate follow-up task is created.

## Out of scope

- Automatic workspace creation for each repository.
- Unbounded recursive import or two-way synchronization of remote documentation.
- Browser-visible forge credentials or direct database credentials in generated snippets.
- Full git worktree management, which remains in `apps/worker`.

## Dependencies

- Epic `connected-repos` for the base schema, CRUD router, and forge adapters.
- Auth.js account linking in `apps/web/lib/auth.ts`.
- Convoy lifecycle schemas and local reconciliation behavior.
- A configured workspace model route, Redis, and worker are runtime dependencies for executing the implementation convoy, not for using the finished repo picker.

## Acceptance criteria

- [ ] A GitHub-linked user or configured Forgejo/Gitea admin sees all accessible repositories through explicit pagination without receiving a token in the browser.
- [ ] An admin selects multiple repos and connects them to the current workspace in an idempotent operation; manual URL connection still works.
- [ ] Supported documentation imports as `document` objects with repo/path/revision provenance and no duplicates on retry.
- [ ] Valid `.convoys/*.md` manifests reconcile into workspace-scoped convoy objects; malformed files are reported without aborting other imports.
- [ ] OpenCode and Cursor setup instructions are syntactically accurate for the supported transport and contain no secrets.
- [ ] Tenant isolation, credential redaction, pagination, idempotency, and partial-failure behavior have automated coverage.

## Tasks

- [ ] [Task-forge-discovery-api](./Task-forge-discovery-api.md)
- [ ] [Task-repo-picker-modal](./Task-repo-picker-modal.md)
- [ ] [Task-repo-doc-ingestion](./Task-repo-doc-ingestion.md)
- [ ] [Task-agent-mcp-starter](./Task-agent-mcp-starter.md)

## Execution convoy

`.convoys/repo-discovery-onboarding.md`