Installing Trusted Layers¶

clauz3 install copies a trusted tools/ layer from one project into another. It is the quickest way to start a new project from an existing example: rather than hand-copying tools/<domain>/trusted/ directories, point install at a source path and it copies each trusted domain for you.

A trusted layer is the tools/ folder of a clauz3 project — the small audited modules under tools/<domain>/trusted/ that the prover trusts (see Effect specs). Everything else (agent-authored programs and their @clauz3.guarantee(...) decorators) is untrusted and proved against this layer.

Signing is still future work

install accepts local filesystem paths, bundled stdlib tools, and git remotes (gh:org/repo, full URLs). A signing mechanism that lets a user verify the installed layer matches what was attested upstream is still future work — see issue #47. Until then, treat an installed layer as trusted only if you trust its source.

Quickstart¶

From an empty project directory, install the email example's trusted layer:

clauz3 install /path/to/clauz3/examples/email

This copies examples/email/tools/email/ to ./tools/email/, giving you the send_email effect and the email contract vocabulary. You can immediately prove a program against it:

clauz3 prove --trusted-root tools/email/trusted plan.py

Source path¶

The source argument may be:

a bundled stdlib tool, written stdlib:<name> (for example stdlib:filesystem); see Standard library tools,
a project directory that contains a tools/ folder (for example examples/email),
a tools/ folder directly (for example examples/email/tools), or
a git remote — either the gh:org/repo shorthand or a full git URL, optionally with @<ref> appended.

Every tools/<domain>/ that contains a trusted/ package is copied. A source with several domains installs all of them.

stdlib tools are located with importlib.resources rather than a filesystem path, so stdlib: sources resolve identically whether clauz3 runs from a source checkout or a pip installed wheel.

Installing from a git remote¶

The shorthand and full-URL forms both clone into a content-addressed cache under ~/.cache/clauz3/sources/<sha>/ and then resolve like a local path.

# GitHub shorthand
clauz3 install gh:normalform-ai/clauz3-tools-autolabs

# Pin to a tag, branch, or sha
clauz3 install gh:normalform-ai/clauz3-tools-autolabs@v0.3.1
clauz3 install gh:normalform-ai/clauz3-tools-autolabs@abc1234

# Full URL (also accepts @<ref>)
clauz3 install https://github.com/normalform-ai/clauz3-tools-autolabs.git
clauz3 install git@github.com:normalform-ai/clauz3-tools-assistant.git

The cache is keyed by the resolved commit sha, not the source string, so multiple invocations against the same upstream sha share a single clone. When a moveable ref (HEAD, a branch, a re-tagged tag) advances upstream, the next invocation resolves the new sha and creates a fresh cache entry. Pinning to @<sha> therefore hits a stable cache entry forever.

Authentication uses git's existing configuration — SSH key, credential helper, or gh auth setup-git. Private repos work the same way once your user has access; clauz3 does not manage credentials itself.

Override the cache location with CLAUZ3_CACHE (defaults to ~/.cache/clauz3).

Options¶

Option	Effect
`--into <dir>`	Destination project root. Defaults to the current directory.
`--force`	Overwrite an existing trusted layer at the destination. Without it, `install` refuses to clobber an existing `tools/<domain>/`.
`--skills`	Also generate `agents/skills/<domain>/SKILL.md` for each installed domain.

clauz3 install /path/to/clauz3/examples/email --into my-project --skills

Generated skills¶

With --skills, install writes one agents/skills/<domain>/SKILL.md per domain. Each file is generated by introspecting the trusted modules: it lists the available effects and contracts with their signatures and docstring summaries, plus a short usage block. For the email example the generated skill documents send_email and the only, none, unique_recipients, at_most, and related contracts.

These are starting points. Edit the generated SKILL.md to match how you want an agent to use the layer.

Relation to integration testing¶

The integration testing guide builds a temporary user repo by hand-copying tools/email/trusted. clauz3 install performs the same copy in one command:

clauz3 install examples/email --into "$TMP_REPO"