The first steps to IZ4.

1. Install the CLI

One line to copy and paste. The format is open and the CLI is free. The installer fetches the single iz4 file published for your system, checks its checksum, proves it runs and puts it on your PATH: no runtime, no Git, no admin rights. Where no file fits your system, it installs from source instead, with Git as the only prerequisite.

curl -fsSL https://raw.githubusercontent.com/nige123/cli.iz4.you/main/install | sh

irm https://raw.githubusercontent.com/nige123/cli.iz4.you/main/install.ps1 | iex

git clone https://github.com/nige123/cli.iz4.you iz4
ln -s "$PWD/iz4/bin/iz4" ~/.local/bin/iz4     # needs Rakudo; or: cd iz4 && zef install .

Keep it current with iz4 update: it brings any install, file or source, to the newest release, and iz4 update check only says whether there is one.

Then, in your repository, iz4 init. It asks what the software is for and who it is for, writes the file, and offers to find a first invariant. Or write it by hand: copy this into a file called IZ4 at the root of your repo and answer the questions. Put the domain your project answers for in the first line, and give each invariant a name: a few lower-case words joined by hyphens. Then iz4 foundation restore writes in the foundation every IZ4 carries, word for word.

IZ4 your-domain.com

IS FOR WHAT?  What is this software for, in a sentence?
IS FOR WHO?   Who is it for?

first-promise:
  WHERE:    The situation it applies in.
  ALWAYS:   What must remain true there, whatever is rebuilt.
  PROTECTS: Whose what must not be defeated.

2. Find your invariants

iz4 add asks three questions, one at a time: where does this apply, what must remain true there, and what does that protect. Where, always, protects. All three bind together: WHERE scopes, ALWAYS binds, and PROTECTS decides what counts as keeping it. None narrows or excuses another.

It also tells you when something is not an invariant. The golden test: if the whole system were rewritten tomorrow, would the people rebuilding it regret not knowing this? "Uses PostgreSQL" fails it. "Private data is permanently deleted when an account is deleted" passes.

With an agent to hand, iz4 suggest proposes a few candidates for you to review. iz4 invariants prints the foundation beside your own, each by name. The human decides what must survive. The tool only asks.

3. Lock them in

Commit the file beside the README. iz4 check ticks what it can verify and says what it cannot. Then hand the invariants to every coding agent before it touches the code:

iz4 agent install          # a managed section in AGENTS.md
iz4 review install         # an advisory pre-push review against the invariants

Every IZ4 carries the foundation, such as human-agency.iz4.you, and nothing written beside them can weaken them. Your invariants sit inside that lock.

Still working out what must stay true? iz4 mode mvp lets your own invariants change without waiting for a yes. iz4 mode solid when they hold. The foundation holds in both.

4. Share in the register

Create a workspace, add your project, and the Connect CI page gives you one command to paste in your repo, which adds this workflow and your token. It reports counts, outcomes and coverage on every push. A private repo's file and code stay in CI. We never access them. From a connected checkout, iz4 register and iz4 report do the same from the command line.

# .github/workflows/iz4.yml
name: iz4
on: [push]
jobs:
  report:
    runs-on: ubuntu-latest
    continue-on-error: true   # advisory: never blocks a release
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 1 }
      - run: |
          curl -fsSL https://iz4.you/iz4-report -o iz4-report
          chmod +x iz4-report
          ./iz4-report --url https://iz4.you/api/v1/projects/YOUR_ID/reports --token "$IZ4_TOKEN" \
              --release "$GITHUB_REF_NAME" --run-id "$GITHUB_RUN_ID"
        env:
          IZ4_TOKEN: ${{ secrets.IZ4_TOKEN }}

Connect CI fills in your project's address and stores the token for you.

Publish, then show your badge

Preview what goes public and publish. Your project page then mints your IZ4 badge, the QR code inside the diamond, for your site and packaging. For your README, drop in the status badge:

[![IZ4](https://iz4.you/p/YOUR_ID/badge.svg)](https://iz4.you/p/YOUR_ID)

From a connected checkout, iz4 badge prints these lines with your own id filled in, offline.

The status badge is live. It shows the card's evidence-backed state, a failed check included. Never a score.

Your card keeps itself current

• Your CI reports on every push, so the card's evidence follows your code without anyone remembering to update it.
• The README badge is an image served by the register. When the evidence changes, the badge changes. There is nothing to paste again.
• You choose which revision the card presents. A report adds evidence but never changes what the card presents. When you release, set the new revision.
• If reports stop for 30 days, the card marks the evidence stale. That says how old the evidence is. It does not judge the project.

5. Pass it on

Software is built on software. Your card counts how many of the projects you depend on declare an IZ4 of their own, and names the ones that do not. Ask them. Every project that answers makes the next request easier, and the ground firmer for everyone standing on it.

Copy this, change the name, and send it wherever that project prefers. The register never contacts anyone on your behalf.

Hello. We depend on this project and would find an IZ4 file useful.

An IZ4 is one plain text file beside your code saying what the software
is for, who it is for, and the few things that must remain true for it
to keep serving them. It helps anyone reading the code, and it helps AI
agents follow your intent rather than guess it. Every IZ4 begins with
the same commitment: the software is for humans first.

There is an open tool and format at https://iz4.you/start, and nothing
needs to be registered or paid for. If it is useful to you, we would be
glad to see one.

Thank you for the work you already do.

Add an IZ4 to a library you maintain and every project standing on it gains a declared dependency the moment its CI next reports.

Register your IZ4 Pricing