Quickstart

Quickstart

This page gives the shortest safe path to useful output.

PIC has two normal use modes:

• install from PyPI for practical checks, bundled demos, schema export, canonical readiness, optional sidecars, and your own inputs;
• clone the repository for full practical workflows with bundled examples, fixtures, and development checks.

Path A: Installed Package

Use this when you want to check that PIC works and run simple local commands.

python -m pip install percolation-inversion-compiler
pic agent explain
pic agent check --compact --text "Candidate packet: route evidence and preserve residuals." --profile development
pic phase plan --compact --text "Candidate packet: route evidence and preserve residuals." --profile development
pic agent accelerate --compact --text "Candidate packet: route evidence and preserve residuals." --profile development
pic agent runbook --profile development
pic agent autonomy-audit --profile development --format json
pic audit canonical-readiness --profile development --format json
pic demo installed-smoke --profile development
pic demo bootstrap --output-dir pic-demo
pic runtime step --state pic-demo/runtime_state.json --input pic-demo/runtime_step_input.json --profile development

This path does not need the source repository.

Path B: Source Checkout

Use this when you want examples, fixtures, local TeX audits, release checks, or full development workflows.

git clone https://github.com/kadubon/percolation-inversion-compiler.git
cd percolation-inversion-compiler
uv sync --all-extras --dev

Then run commands through uv:

uv run pic agent explain
uv run pic agent guide --profile development
uv run pic agent readiness --profile development
uv run pic agent doctor --profile development
uv run pic agent check --compact --text "Candidate packet: route evidence and preserve residuals." --profile development
uv run pic agent intake --text "Candidate packet: route evidence and preserve residuals." --profile development

Read The First Report

After an intake command, inspect:

• accepted
• workflow_usable
• operationally_usable
• settled
• missing_obligations
• residual_ledger
• agent_tasks
• route_execution_requests

Useful output often has settled=false. That means PIC preserved unresolved work instead of pretending the claim is complete.

Production Identity Flow

For production packet promotion, derive accepted identity context first.

uv run pic identity derive-context --population examples/agent_population_signed.json --profile production --output identity-context.json
uv run pic agent intake --text "Signed packet candidate." --profile production --identity-context identity-context.json

Cryptographic identity proves protocol-relative key control. It does not prove legal identity, real-world personhood, or global uniqueness.

Network And External Intake

Offline examples are safe starting points:

uv run pic agent communication-guide --profile development --no-allow-live-connectors
uv run pic agent network-readiness --profile development --no-allow-live-connectors
uv run pic ecology ingest-general --source examples/agent_network/feed.xml --kind rss
uv run pic ecology ingest-general --source examples/agent_network/page.html --kind web-page

In v0.4.4, live HTTP/feed intake is live-capable by default only when an explicit source is supplied. It is still bounded, candidate-only, and fail-closed. Use --no-allow-live-connectors for local-only dry runs.

uv run pic ecology ingest-general --source https://example.org --kind web-page
uv run pic ecology ingest-general --source https://example.org --kind web-page --no-allow-live-connectors

External content remains a candidate until verifier, semantic edge, identity, rollback, and residual policies pass.

Optional Sidecars

Sidecars are extra reports for handoff, exchange, and observation. They do not block the core commands and they do not set settled=true.

pic adoption packet --profile development --format markdown
pic phase benchmark-suite --profile development --format json
pic phase dashboard --profile development --format json
pic packet inspect --packet pic-demo/packet_envelope.json

Local Agent-To-Agent Relay

Use this when one agent needs to pass candidate work to another agent through a local inbox file.

uv run pic agent message send --inbox inbox.json --sender agent:alice --text "Candidate packet: preserve residuals."
uv run pic agent message receive --inbox inbox.json
uv run pic agent inbox verify --inbox inbox.json
uv run pic agent relay-readiness --profile development

Local relay output is still diagnostic candidate material. Production or adversarial promotion requires identity context and replay checks.

Next Pages

• Concepts in Plain Language
• Agent Guide
• Optional Sidecars and Agent Autonomy
• CLI Recipes