Start here

Installing Kits

A Kit supplies a ready-made tracking model for a particular kind of machine, software stack, or workflow. It can define what to track, identify the software involved, supply useful Profiles and reference data, and include guidance from the Kit author.

kit is a separate, downloadable, distributable, add on package of pinman assets you can import into a project

A Kit is added to Pinman in two steps:

Install adds the Kit to this machine's Kit library, where any Project can find it by name.
Import adds the Kit's content to the active Project and records that the Project has adopted it.

This separation lets several Projects use one installed Kit. It also gives you a chance to inspect community content before it changes a Project.

What a Kit contains#

Every Kit has a kit.yaml manifest. Its other folders are optional and serve different purposes:

Content	What happens when the Kit is imported
`schema/`	Software Catalog entries and Schema Items merge into the Project.
`reference/`	Catalogs, blacklists, and guided instructions remain in the installed Kit and are read when Pinman needs them.
`profiles/`	Profile scripts are copied into the Project and synchronized.
`docs/`	Guidance remains with the Kit for the user or Kit author.

Kits carry domain content and guidance, not Pinman platform code, adapters, or application binaries. Profile scripts are Python and are the Kit's executable content.

Importing is an additive Project change, not a temporary attachment. The Kit's Schema merges into the Project, and uninstalling the library copy later does not undo that merge.

Choose a Kit#

List the Kits available on this machine and the Kits already adopted by the active Project:

pinman kit list

Choose a Kit that matches the machine or software you want Pinman to track and manage. The blank Kit provides only the empty realm structure for a Project you intend to define yourself.

A Kit can require other Kits. Those dependencies must also be installed; Pinman imports them before it imports the Kit you selected.

For community content, review the source, origin, and disclaimer before you import it. The origin identifies the publisher but is not a security review. Pinman shows the disclaimer and asks for confirmation at import time, when the Kit's executable content can run.

Install a downloaded Kit#

Download the Kit's .zip, then add it to this machine's Kit library:

pinman kit install .\example-kit-1.0.0.zip

Installation validates and copies the package. It does not change the active Project. Once installed, the Kit is available by its manifest name to every Project on this machine.

To replace a previously downloaded copy with a newer version, use --force:

pinman kit install .\example-kit-1.1.0.zip --force

Kits bundled with Pinman are already available and do not need this installation step.

Import the Kit into a Project#

Make the intended Project active, then import the Kit by name:

pinman kit import example

Pinman imports required Kits first, merges the Kit's Schema, adds its other Project content, and records the adopted Kit and version. Repeating the command for a Kit the Project already uses changes nothing.

You can install and import a downloaded Kit in one command:

pinman kit install .\example-kit-1.0.0.zip --import

You can also adopt one or more available Kits while creating a Project. Repeat --kit to preserve the order in which several Kits should be imported:

pinman project create my-machine --kit example

The guided pinman setup command offers the same choice during first-run setup.

Read the newly tracked state#

After importing, Refresh the Head or create a Capture so Pinman reads the Items the Kit added to the Schema. Software detection can then resolve path anchors that activate Items whose locations were not previously known. Profiles from the Kit are available after synchronization.

Check the active Project's Kit setup with:

pinman kit check

The check reports missing installed Kits, dependency problems, version drift, reference-file collisions, and invalid or conflicting software path-anchor names.

Update a Kit#

Updating has the same two scopes as the original installation. First replace the machine's library copy, then deliberately re-import it into the Project:

pinman kit install .\example-kit-1.1.0.zip --force
pinman kit import example --force

The second command merges the updated Kit content and reasserts its authored Schema values. Review the Kit changes first if you have edited those parts of the Project locally.

Uninstall a downloaded Kit#

Remove a downloaded Kit from this machine's library with:

pinman kit uninstall example

This removes the installed package, not content already merged into a Project. Pinman does not provide an unimport operation. Create a new Project without the Kit when you want a clean Project that never adopted it. Kits bundled with Pinman cannot be uninstalled.