# Aeonora Quickstart

Requirements: Node.js 22+ and npm.

## Install

```bash
npm install
npm link
```

## Validate

```bash
aeonora validate examples/duckman.aeonora.json
```

## Create controller keys

```bash
aeonora keygen .aeonora/controller-key.json
aeonora bind-controller examples/duckman.aeonora.json .aeonora/controller-key.json .aeonora/duckman.json
```

## Store encrypted snapshots on your own IPFS node

Start the pinned Kubo node described in `infra/ipfs/README.md`, then initialize portable agents with:

```bash
AEONORA_BLOB_STORE=ipfs IPFS_API_URL=http://127.0.0.1:5001 \
  aeonora-portable init ./my-agent hermes .aeonora/my-agent
```

The saved `blobCid` is an `ipfs://` content address. Keep `IPFS_API_URL` set for restore, migrate, verify, push, pull, and connect commands. The node receives only the encrypted envelope.

Private key controls agent. Keep it secret and backed up. Never commit `.aeonora/`.

## Register

```bash
aeonora register .aeonora/duckman.json .aeonora/controller-key.json
export AEONORA_AGENT_ID='aeonora:local:replace-with-returned-id'
```

## Resolve, verify, and authorize

```bash
aeonora resolve "$AEONORA_AGENT_ID"
aeonora verify "$AEONORA_AGENT_ID"
aeonora authorize "$AEONORA_AGENT_ID" research
aeonora authorize "$AEONORA_AGENT_ID" delete
```

`verify` recomputes every commitment, checks controller signatures, and verifies version lineage. Example `research` is allowed; `delete` denied.

## Migrate runtime

Copy manifest, change `runtime.id` and `runtime.codeCommitment`, then:

```bash
aeonora migrate "$AEONORA_AGENT_ID" migrated.json .aeonora/controller-key.json
aeonora verify "$AEONORA_AGENT_ID"
```

Agent ID stays unchanged. Lineage gains signed version and migration receipt.

## Suspend

```bash
aeonora suspend "$AEONORA_AGENT_ID"
aeonora authorize "$AEONORA_AGENT_ID" research
```

Suspended agent receives denial.

## Embed

```js
import { LocalAeonoraRegistry } from "./packages/aeonora/local-registry.mjs";

const aeonora = new LocalAeonoraRegistry(".aeonora/registry.json");
const decision = await aeonora.authorize({
  agentId: process.env.AEONORA_AGENT_ID,
  action: "research"
});
if (decision.status !== "allow") throw new Error(decision.reason);
```

## Verify repository

```bash
npm run check
```

Local registry is reference implementation. Do not describe local records as on-chain until real transaction receipt exists.

## Anchor on a local EVM chain

Start an EVM development node with unlocked accounts, then compile and deploy:

```bash
npm run compile:contracts
RPC_URL=http://127.0.0.1:8545 DEPLOYER=0xUnlockedAccount npm run deploy:rpc
```

Use a funded controller key for signed registry writes:

```bash
export RPC_URL=http://127.0.0.1:8545
export AEONORA_REGISTRY_ADDRESS=0xAddressFromDeployment
export AEONORA_PRIVATE_KEY=0xControllerPrivateKey
aeonora-chain register examples/duckman.aeonora.json
aeonora-chain resolve 0xAgentIdFromRegistration
aeonora-chain verify-anchor 0xAgentIdFromRegistration examples/duckman.aeonora.json
```

The deployment account is only used to deploy this permissionless registry. The controller key owns its agent entry. Never commit or print production private keys.