Skip to content

Packages

Jump to bottom
sarr-io edited this page Jun 6, 2026 · 28 revisions

Packages

A Zinc package is an installed capability. It can ship prompts, files, graphs, scripts, and external tools.

Packages are explicit. Installing a package can patch the local loop graph, but the resulting graph still shows which prompts and tools were added.

Official optional packages live in darkhorseprojects/zinc-packages. Core Zinc installs no optional packages by default.

Manifest

Package metadata lives in zinc.pkg.yaml:

name: hello
version: "0.1.0"
description: Tiny Zinc package example.

assets:
  prompts:
    hello_prompt: prompts/hello.md

scripts:
  check:
    linux: scripts/check
    macos: scripts/check
    windows: scripts/check.cmd

install:
  model:
    input:
      - prompt:hello_prompt
    tools:
      - hello_process

Install patch

The install.model patch declares what should be added to the selected model resource:

install:
  model:
    input:
      - prompt:guide
      - file:manual
    tools:
      - package_tool

Prompts are not loaded by name alone. Tools are not callable by name alone. They must appear in the graph model resource.

Generated wiring

Local package installs write generated package resources to:

.zinc/generated/packages.circuitry.yaml

The local loop graph imports that generated file and references package resources through the packages namespace:

imports:
  packages: "/path/to/project/.zinc/generated/packages.circuitry.yaml"

resources:
  assistant:
    model:
      input:
        - packages.example_prompt

Package layout convention

Official packages use this layout:

.zinc/packages/<name>/                 installed package code and assets
.zinc/config/packages/<name>.yaml      user/project package config
.zinc/runtime/packages/<name>/         package working runtime

Package authors should follow the same convention.

Use .zinc/packages/<name> for source files shipped by the package:

  • zinc.pkg.yaml
  • prompts/
  • tools/
  • scripts/
  • graphs/
  • assets/
  • vendored third-party source and attribution

Use .zinc/config/packages/<name>.yaml for user choices.

Use .zinc/runtime/packages/<name> for venvs, compiled helpers, setup-created files, and downloaded working files.

Self-contained but not messy

Packages should be self-contained capabilities. A package can vendor code, include scripts, and create the runtime it needs.

Self-contained does not mean storing everything inside the installed package directory. Installed package directories should be replaceable. Runtime files belong in .zinc/runtime/packages/<name> and user choices belong in .zinc/config/packages/<name>.yaml.

Source syntax

GitHub shorthand:

github:<owner>/<repo>/<package-path>#<tag-or-branch>

Example:

zn pkg add --local github:owner/repo/packages/example#v1.0.0

Local development path:

zn pkg add --local --replace /path/to/package

Scripts

Scripts are package maintenance commands:

zn pkg exec example setup
zn pkg exec example check

A good package has a check script when setup depends on local capabilities.

Tool handlers

Package tool handlers are external only:

  • process
  • http
  • mcp

Graph execution stays built into Zinc through run_graph rather than being a package handler.

Author rules

  • Keep the manifest small and readable.
  • Make setup/check scripts cross-platform when possible.
  • Put normal user choices in config files, not environment variables.
  • Keep runtime artifacts out of installed package directories.
  • Include attribution for vendored third-party work.
  • Make tool success honest and narrow.

Clone this wiki locally