jackin join & Debug Export

Status: Open — research and design proposal

Problem

Two operator-facing gaps that need research before design:

1. No project-level onboarding flow. Workspaces live in per-operator host config. A project that wants to say "here's how to set up the dev environment for this repo" has no mechanism. Every new contributor configures from scratch. The concept of jackin join <org>/<project> — where the project repo contains workspace configuration and jackin' guides the user through setup — needs exploration.

2. No reproducible debug export. When someone reports a bug, they paste a backtrace + run-id. The maintainer guesses at the workspace/role/config state. No way to share a reproducible, redacted bundle.

Proposal

Part 1 — jackin join <org>/<project>

Research the concept of project-level onboarding:

$ jackin join chainargos/chainargos-monorepo

This would:

1. Check the organization/project on GitHub.
2. Look for a jackin' workspace configuration file in the repo.
3. Analyze the project — find workspace definitions (e.g., "backend", "frontend", "shared-libs").
4. Present a rich TUI wizard that guides the user through:
   • Which workspaces to set up.
   • Credential configuration (without leaking sensitive details — the wizard shows "1Password will be resolved here" not vault/item specifics).
   • Local directory preferences.
5. Clone the repository, configure workspaces, download agent roles.
6. Get the user to a working state immediately.

Key research questions:

• How should multi-workspace monorepos be represented in the project config?
• How does credential configuration work without leaking secrets?
• Should jackin join also install local prerequisites, or does everything run in containers?
• What file format should the project-level config use? (A new file? Extending jackin.role.toml?)
• Trust model: project configs come from external repos — do they need trust grants like role sources?

Part 2 — Debug export bundle (diagnostic command)

A diagnostic command (name TBD — jackin debug, jackin diagnostics export, or similar) that extracts a redacted .tar.zst bundle by run-id:

$ jackin debug export <run-id>

The bundle contains:

• Redacted workspace config (secrets replaced with placeholders).
• Redacted role manifest.
• Redacted env list (shows "will be resolved from op://" but not vault/item details).
• The relevant diagnostics JSONL from ~/.jackin/data/diagnostics/runs/<run-id>.jsonl.
• Capsule version, jackin version, OS info.
• Container runtime details.

Redaction rules:

• All 1Password references show "1Password will be resolved" without vault, item, or field names.
• All API keys/tokens show <redacted> for values but preserve key names.
• Environment variable values that match known secret patterns are redacted.
• File paths are preserved (they're not sensitive).
• Docker container names, image names, and network names are preserved.

This is useful for both human debugging and feeding to AI agents for analysis — the agent gets a clear JSONL file plus structured context without any sensitive data.

Non-goals

• Do not implement jackin join yet — this is a research/design item.
• Do not create a jackin import counterpart for the debug bundle (the bundle is for diagnostics, not reproduction).
• Do not store debug bundles on any remote server — they stay local.

Implementation Phases

Phase 1 — Debug export command

Implement the diagnostic export command with full redaction. This is the more tractable half and can ship first.

Phase 2 — jackin join research

Research UX patterns from Devcontainers, Nix flakes, mise, and similar tools. Document the proposed flow. Design the project-level config format.

Phase 3 — jackin join prototype

After research converges, build a console-native TUI wizard prototype.

Open Questions

1. What is the right name for the debug export command? (jackin debug, jackin diagnostics export, jackin export-debug?)
2. Should the project-level config be a new file (jackin.project.toml) or reuse the workspace config?
3. How should jackin join handle private repositories (authentication)?
4. Should the debug bundle be encrypted or just redacted?

Related Files

• crates/jackin-diagnostics/src/run.rs — existing diagnostics framework
• crates/jackin-env/src/resolve.rs — env resolution (redaction source)
• crates/jackin-runtime/src/instance/auth.rs — credential locations (redaction targets)

Cross-references

• /reference/roadmap/operator-cli-hygiene/ — doctor and status commands complement the debug export
• /reference/roadmap/agent-orchestrator-research/ — workspace-as-code concept
• /reference/roadmap/jackin-desktop-agent-hub/ — desktop hub could consume debug bundles