Markdown edition

# Install and verify a Journey kit, then share your own workflow

> Inspect and install an exact Journey kit release, check its first use, then package a workflow you have already tested and verify that a teammate can install your release.

By BIGCHANGE.AI Editorial

Published: 2026-10-24T19:40:38.270Z
Updated: 2026-10-24T19:40:38.270Z
Canonical: https://bigchange.ai/blog/journey-kit-install-verify-share-workflow-guide

![Conceptual charcoal illustration of blank file sheets emerging from an open cloth envelope, beside an empty file sleeve.](https://bigchange.ai/api/media/file/journey-kit-file-handover-hero-v2.png)
AI-generated conceptual illustration by BIG CHANGE.

Journey can distribute an agent workflow as a kit, but finding a kit and installing it are only the start of a handover. The useful result is a checked installation, a first run against an allowed task, and a released version of your own workflow that a teammate can install and check in turn. This guide uses Journey's published documents and the `journeykits` 0.2.0 CLI. BIG CHANGE has not installed a kit, run a model or published a release for this article.

You need an agent workspace and harness you control, Node.js 20 or newer, npm, and permission to read the source kit and every dependency. For the sharing steps, bring a *different* workflow you own, its source revision, an earlier accepted run, its actual input and output, and redistribution rights. Publishing requires an existing Journey agent API key with `kits:write` and a verified email. Check Journey account terms, any organization restrictions, kit licenses and model or service charges before proceeding.

## The big change

- **What changed:** Journey's install response supplies kit files, dependencies and checks; the installed version and real task output still need local verification.
- **Why it matters:** A released kit can be handed to a teammate. A draft bundle or pending release does not prove that they can find and use it.
- **What to watch:** The checked CLI can fall back to `latest` for an unversioned dependency and can skip a kit's shell preflight while recording a passed badge. Review and pin the entire dependency tree before a write.

## 1. Choose an exact kit and target

Check your local versions, then install and inspect the documented CLI version. Run `journey targets` to confirm your actual harness is supported; `claude-code` below is only the target used to show command shape.

```sh
node --version
npm --version
npm install -g journeykits@0.2.0
journey --version
journey targets
journey search "YOUR ACTUAL TASK"
```

Stop if Node is below 20, the installed CLI is not 0.2.0, or its help differs from the flags here. Choose one `OWNER/SLUG` and an immutable released `RELEASE_REF`. Do not use `latest`. Read the kit's setup, steps, constraints, safety notes, license, required services, secrets and target support. The search result and registry quality score are leads for inspection, not proof of safety or suitability.

## 2. Inspect every dependency before installation

Request the selected kit's [install response](https://www.journeykits.ai/api/kits/journey) for your target and immutable ref. This is the URL shape; replace every capitalized value with the actual inspected release and target:

```text
GET https://www.journeykits.ai/api/kits/OWNER/SLUG/install?target=TARGET&ref=RELEASE_REF
```

Compare the response identity, ref and files with the release you selected. The CLI offers a no-write comparison for the same exact identity:

```sh
journey install --kit OWNER/SLUG --ref RELEASE_REF --target TARGET --dry-run --json
```

Compare its `kitRef`, `ref`, target and file list with the API response. Missing, changed or untrusted identity or content means **hold before writing a file or running any kit command**. A dry run alone does not establish that subsequent dependency installation or commands are safe.

Expand `dependencyKits` recursively until no new node remains. For each node, record its requested version, actual immutable ref, `kitRef`, license, target support, file contents and paths, `writeMode`, required services and secrets, and every preflight and verification command with its shell/runtime. Obtain that node's exact-ref install response and compare the identity and files; use an exact-ref dry run where supported. Inspect any existing install lock against the requested **version and ref** and installed files, not just the name. If a dependency has no version, resolve a fixed released ref from its release record and repeat the comparison. Hold if a version cannot be fixed, a node is inaccessible, content drifts, two versions conflict, a cycle appears, a command cannot be reviewed, or rights are missing.

The 0.2.0 CLI's parent install recursively processes dependencies. Its dependency code substitutes `latest` when a dependency version is absent and treats an existing lock entry with the same `kitRef` as sufficient without checking its version. Using `--strict` or `--verify` can also run a new dependency's verification through `sh -c` without a top-level `--yes` approval. These flags are not a safety check for this procedure.

For a kit with dependencies, apply the reviewed [API install responses](https://www.journeykits.ai/api/kits/journey) **bottom-up** in an owned disposable workspace. Before each write, recompare the response's identity, ref and files with the saved reviewed node. Write only the reviewed paths and contents, respect `writeMode: append` and existing content, and record the installed version and files for every node. Follow the response's compatibility notes and `nextSteps`. If you cannot faithfully apply a response, hold; a parent CLI install could revisit the dependency tree. A dependency-free kit may instead use this exact-ref CLI route after the checks below:

```sh
journey install --kit OWNER/SLUG --ref RELEASE_REF --target TARGET
```

Before installing **each node**, have the workflow owner approve its exact required preflight commands, working directory, shell, permissions and side effects. Run them manually in that setting and record each real exit code and output. A failed or unknown result stops installation. The checked CLI skips kit-supplied shell preflights yet records `passed: true` with a skipped message; that badge is not an executed check. Check CLI availability and required secrets yourself as well. Do not run the command above with `--strict`, `--verify` or `--yes` as a substitute for this review.

After installation, compare actual files and refs for all nodes with the reviewed responses and inspect the installed `kit.md`. Manually run only owner-authorized verification commands in their supported shell, using permitted input. Compare their real exit and output with a success condition written down before the run, then try the kit on the allowed first-use task and record the observed result. Installation success is not task success. If a check fails, inspect paths, append behavior, dependencies, permissions and compatibility notes before one bounded retry. Record one truthful completed, partial, blocked or failed install report using the response's `tracking` object where available; an outcome report after first use is optional and needs the user's consent.

## 3. Turn your own proven workflow into a kit

Use a separate workflow whose real inputs, files and earlier accepted result you can show. Record its source revision, expected output, observed failure and recovery, exact model/runtime and hosting, service dependencies, costs and sharing rights. A prompt with no observed working route is still a draft. The CLI can start a bundle directory:

```sh
journey share "YOUR VERIFIED WORKFLOW RESULT" --slug your-workflow-slug --title "YOUR RESULT TITLE" --model-provider YOUR_PROVIDER --model-name YOUR_EXACT_MODEL_ID
```

In the returned directory, complete `manifest.json` and `kit.md` using the [publishing format](https://www.journeykits.ai/api/kits/publish-to-journey) and [kit.md specification](https://www.journeykits.ai/api/docs/kit-md). Give the manifest a semantic version and truthful tags, inputs, outputs, failures overcome, tool or skill, verified model and hosting, prerequisites, services, parameters and environment. Write substantive Goal, When to Use, Setup, Steps, Constraints and Safety Notes sections in `kit.md`. Include the actual tested scripts or config as `srcFiles` with matching `fileManifest` paths when the workflow needs them. Set `selfContained` to false and name the external workspace or service if files alone cannot run it. Declare the harness you actually tested in `testedHarnesses`.

Inspect every bundled file for secrets, personal data, private URLs, company material, unsafe commands and third-party code without redistribution rights. Replace sensitive values with documented inputs or omit material and state the resulting limit. Public visibility requires permission to distribute the whole bundle to anyone. Organization-private sharing requires a supported account and verified team access.

## 4. Test, release and check the recipient's result

Run the local validator on the real draft directory and fix each finding:

```sh
journey validate PATH_TO_YOUR_KIT_DIRECTORY
```

Before release, specify a safe negative input from the actual workflow, such as a missing required input or unsupported target, and predeclare the stop condition: no output artifact, external action or release request. Run it only in an authorized disposable workspace after reviewing commands. Record the actual file/state diff, output and requests. If it does not stop as expected, repair the workflow and repeat. Separately, test the bundle's actual files in a clean authorized workspace with a positive input; record preflight exits, output and recovery. No registry install URL exists for an unreleased draft.

Check `journey whoami`, the existing `kits:write` scope, verified email and the owner's explicit visibility choice. For an organization-private release, verify the real `ORG_ID`, ownership and recipient membership. Review the exact bundle and release note before making **one** publish request. The 0.2.0 CLI defaults to public, so name the chosen visibility:

```sh
journey publish PATH_TO_YOUR_KIT_DIRECTORY --visibility public --changelog "Initial checked workflow and setup requirements"
```

For an approved private organization release, use this command instead:

```sh
journey publish PATH_TO_YOUR_KIT_DIRECTORY --visibility private --org ORG_ID --changelog "Initial checked workflow and setup requirements"
```

The checked CLI uses `--changelog`; an online example's `--release-notes` is not verified for 0.2.0. Its publish command validates, imports and creates a release by default, so do not duplicate the write through a raw import or release API. Record the returned revision, release ref, visibility, organization, status and findings. A revision without a release is a draft; a pending release is not confirmed discoverable. Check the exact public `owner/slug` release status, or authorized organization access for a private kit.

Give a permitted teammate the **exact released ref**. They must repeat the recursive dependency, lock, file, command and rights checks from step 2 in their own target; manually run authorized preflights and verifications; and compare installed files and first-use output. A dependency-free released kit can use the exact `--kit` and `--ref` CLI command above, adding `--org ORG_ID` only for an authorized private organization install. A search hit shows discoverability; the teammate's checked files and task result show whether the handover worked. Missing access, a failed scan, a pending release or an unverified recipient leaves a specific hold.

Keep an acceptance record with actual versions, exact refs and dependency closure, command exits and outputs, prior source-workflow result, safe negative and positive tests, visibility and release status, and the teammate's result. Leave unobserved fields `UNKNOWN`. Kit instructions and code run with the recipient's permissions; review them as untrusted input. Registry scanning cannot establish factual correctness or harmless behavior, and model or service use may incur separate charges.

Copy this record before starting. Fill it with observed values; `UNKNOWN` never means pass.

```text
Owner, date, workspace and permitted harness:
Journey document version/date; npm metadata URL/version; Node/npm/CLI readbacks:
Selected OWNER/SLUG@IMMUTABLE_REF, license and target:
Expected source identity/ref and file list:
Exact API install response and CLI dry-run identity/ref/file comparison:
Every recursive dependency: kitRef, requested version, immutable actual ref,
  license, target, response identity, file hashes/paths/writeMode,
  services/secrets, commands and required shell/runtime:
Missing-version, cycle, conflict, changed-ref or inaccessible-node result:
Existing lock: each node's kitRef, version/ref and installed-file comparison:
Each required preflight: owner permission, workspace/shell, manual exit/output:
Install route: bottom-up API or dependency-free exact-ref CLI;
  reviewed files, append/create handling, installed ref/version for each node:
Each manual verification: owner permission, shell, exit/output, accepted result:
Permitted first-use input, predeclared success condition and actual output:
Owned separate workflow source revision, rights, earlier accepted run/result:
Bundle path/version, exact model/hosting, services/cost and shipped files:
Negative input and predeclared no-output/no-external-action/no-release stop;
  actual output, file/state diff and requests:
Clean-workspace positive input, preflight exits, output and recovery:
journey validate exit/output and unresolved findings:
journey whoami identity, kits:write and verified-email readback:
Owner's explicit public or org-private choice; if private, owning ORG_ID
  and recipient membership readback:
Single publish command/result: revision, release ref, visibility/org,
  status, findings and exact discoverability/access readback:
Recipient exact API and dry-run ref/identity/file readbacks; full recursive
  dependency/lock review; authorized preflights, install, verification/output:
Decision COMPLETE / PARTIAL / HOLD; exact error and next safe action:
```

## Sources & further reading

- [Journey kit and install API](https://www.journeykits.ai/api/kits/journey): response shape, install and tracking behavior; document version 2026.04.13 in the 24 October 2026 readback. It does not establish a successful installation here.
- [Publishing to Journey](https://www.journeykits.ai/api/kits/publish-to-journey): bundle, validation, account and release path; document version 2026.04.13. Live account eligibility and release status must be checked by the owner.
- [Kit.md specification](https://www.journeykits.ai/api/docs/kit-md): required kit instruction sections and file contract; specification v1.0, document version 2026.03.28.
- [`journeykits` 0.2.0 npm metadata](https://registry.npmjs.org/journeykits/0.2.0): Node engine and distributed CLI version. The checked package code supplied the flag and dependency/preflight limits described above; inspect the installed CLI again when using this guide.
- Related BIG CHANGE guides: [hand over a Claude Code skill](https://bigchange.ai/blog/claude-code-team-faq-source-check-skill-handover) and [build a Codex skill from accepted work](https://bigchange.ai/blog/codex-skill-from-accepted-work-guide) cover adjacent handovers, while this procedure covers Journey installation, release and recipient verification.

## Sources

- [Journey kit and install API](https://www.journeykits.ai/api/kits/journey) — Install response, dependency, preflight and tracking contract; document version 2026.04.13.
- [Publishing to Journey](https://www.journeykits.ai/api/kits/publish-to-journey) — Bundle, validation, account, visibility and release contract; document version 2026.04.13.
- [Kit.md specification](https://www.journeykits.ai/api/docs/kit-md) — Kit instruction sections and file contract; document version 2026.03.28.
- [journeykits 0.2.0 npm metadata](https://registry.npmjs.org/journeykits/0.2.0) — Node >=20 package engine and immutable package version; distribution code inspection in approved packet establishes CLI flag and recursion behavior.