# jackin join & Debug Export (https://jackin.tailrocks.com/reference/roadmap/jackin-join-and-debug-bundle/)



**Status**: Open — research and design proposal

## Problem [#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 [#proposal]

### Part 1 — `jackin join <org>/<project>` [#part-1--jackin-join-orgproject]

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) [#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 [#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 [#implementation-phases]

### Phase 1 — Debug export command [#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 [#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 [#phase-3--jackin-join-prototype]

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

## Open Questions [#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 [#related-files]

* <RepoFile path="crates/jackin-diagnostics/src/run.rs">crates/jackin-diagnostics/src/run.rs</RepoFile> — existing diagnostics framework
* <RepoFile path="crates/jackin-env/src/resolve.rs">crates/jackin-env/src/resolve.rs</RepoFile> — env resolution (redaction source)
* <RepoFile path="crates/jackin-runtime/src/instance/auth.rs">crates/jackin-runtime/src/instance/auth.rs</RepoFile> — credential locations (redaction targets)

## Cross-references [#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