# QNE Doctrine Agent Rules

This is the master QNE-wide agent rules file. Project `AGENTS.md` files should
be derived from this file and reduced to the rules relevant to that project
version. Agents must treat a project `AGENTS.md` as the immediate operating rule
for the current project, and use doctrine as routed context rather than prompt
bulk.

## Doctrine Loading Rule

- Read the project `AGENTS.md` first.
- Use `~/QNE-doctrine/manifest/current-doctrine-index.md` or a bundled project
  copy of `doctrine/manifest/current-doctrine-index.md` to find relevant current
  doctrine.
- Do not read all doctrine by default.
- Read future doctrine only when a task touches founder vision, future
  product/community direction, canonical reconciliation, historical provenance,
  or an explicit doctrine-review task.
- If a doctrine rule becomes durable project policy, summarize it in the
  project `AGENTS.md`.

## Doctrine Promotion Guarantee

When new durable doctrine is created inside a project, the project is not complete
until the authoritative doctrine set is updated. The update must either:

- promote the rule into `~/QNE-doctrine/qnerules.md` when it is QNE-wide agent
  behavior;
- add or update a routed file under `~/QNE-doctrine/current/` when it is current
  operational doctrine; or
- record it in the review or conflict log when it is future-facing, disputed, or
  not ready for current operation.

After updating local doctrine, upload the verified `~/QNE-doctrine` tree to QNE
encrypted online storage. Project-specific `AGENTS.md` files must then be
regenerated or adjusted from the updated master rules.

## Project AGENTS.md Generation Rule

`~/QNE-doctrine/qnerules.md` is the master source. Each project version must
carry a smaller project `AGENTS.md` generated or reviewed from the master rules,
plus project-specific rules and acceptance criteria.

The project `AGENTS.md` must include only rules relevant to that project version
and the work agents are expected to do there. Do not copy the whole master rules
file into every project prompt, and do not include unrelated future doctrine
just because it exists.

When generating a project `AGENTS.md`:

- include QNE-wide rules that affect the project directly;
- include project-specific build, test, storage, installer, network, and safety
  rules;
- include routed references to doctrine files when deeper context may be needed;
- omit unrelated future-product, community, historical, or superseded doctrine;
- keep the project `AGENTS.md` concise enough to be useful on every prompt.

Project zips may include `doctrine/qnerules.md` as a reference copy, but the
active prompt rules should remain the concise project `AGENTS.md`.

## Two-Level Doctrine Rule

QNE doctrine has two authority levels:

- `current`: active implementation doctrine and QNE-wide operating rules. This
  is the only doctrine level bundled into project zips by default.
- `future`: founder vision, speculative product/community design, historical
  provenance, superseded material, and doctrine review notes. Future doctrine is
  preserved for context but is not an implementation instruction until promoted
  into current doctrine.

Do not create additional authority levels such as `long-term`, `historical`, or
`archive` as peer doctrine levels. Those are categories inside future doctrine,
not separate rule sources.

## Project Version Immutability Rule

Every durable change to a QNE project must create a new project version. Do not
patch, overwrite, or silently mutate an existing version as if it were the same
release.

Examples:

- Change `qne-node-v00600` by creating `qne-node-v00601` or the next appropriate
  version.
- Change `qne-online-storage-tool-v00013` by creating
  `qne-online-storage-tool-v00014` or the next appropriate version.
- Keep old version zips and source trees available for provenance unless an
  explicit cleanup/archive task says otherwise.

## QNE Source Authority Rule

QNE does not use or recognize external source-control systems as project
authority. QNE project authority is source code plus current doctrine packaged
as QNE source zips, stored and transferred through QNE-approved storage and
publishing tools.

Agents must not propose, require, document, or implement workflows based on
external source-control hosting, pull requests, branches, commits, forks, or
issues. Project code and project documentation must not mention those systems or
treat them as part of QNE development. Use QNE source zips, doctrine zips,
versioned project directories, and QNE project zip authority instead.

Same-version edits are allowed only as temporary working-copy edits before that
version is published or used as an authority artifact. Once a project zip,
installer, binary, or source tree has been published, installed, uploaded, or
used by another project, fixes must move to a new version.

Project zips, installer downloads, tool binaries, and source archives must make
the version boundary visible in their names and manifests.

## Rust-First Automation Rule

QNE operational automation belongs in Rust code by default. Bash, PowerShell,
batch files, and other shell scripts are allowed only as tiny unavoidable
launchers or platform bridges when Rust cannot reasonably perform the OS action
directly.

Do not add new non-trivial shell or batch logic. If automation needs loops,
retries, parsing, cloud mutation, deletion, installer behavior, secrets access,
status reporting, or cross-platform behavior, implement it in Rust and test it
there.

Existing scripts are technical debt. When touching a scripted workflow,
retrospectively migrate the behavior into Rust unless there is a clear
temporary blocker.

## Development Network Rule

For the `qne-node-v00600+` active bootstrap, current development-network naming supersedes
older alpha-network naming.

Current names:

- `qne-development-network`
- `development-master-0001`
- `development-seed-master-0001`
- `development-skill-repo-0001`

Current seed endpoint:

- `development-seed-master-0001 [2a01:4f9:c010:dc18::1]:7001`

Current base-node install layout:

- `~/QNE/qne-node/persist`
- `~/QNE/runtimes/qne-node-v00xxx`
- `~/QNE/users`
- `~/QNE/logs`

The first development-network milestone uses qne-nodes only. User IDs,
`users/<base36>` persist directories, member onboarding, and user migration are
future milestones unless a project explicitly enables them.

The base qne-node is the permanent QNE node runtime with a minimal capability
set, not temporary bootstrap scaffolding. A full user install adds the separate
UI crate/app, user onboarding, and user-facing qneskills on top of the same node
runtime.

Presence and liveness are handled by the current
`qneskill-node-presence` skill for the project version. Liveness traffic is needed only when no
other qneskill data has moved across a session during the liveness interval, or
when a presence lease needs refresh. P2P transport must always use the
black-box `qne-p2p` dependency. `qne-node` and qneskills must not implement
parallel raw UDP, custom handshakes, custom p2p framing, or replacement p2p
session logic outside that dependency.

Presence is the resource-bounded replacement for old known-node caches. A normal
node stores its own current presence, active/recent contact presence, records
relevant to its users/communities, and a bounded cache learned through
DHT/contact/gossip paths. Normal-node defaults are:

- `max_presence_records = 5000`
- `max_presence_age = 24h`
- `max_presence_bytes = 32MB`
- `presence_ttl = 15m`

Presence records are node-level, temporary reachability/capability records.
User nicknames/contact aliases must not be stored in node presence. Routing is
layered as `nickname -> user_id -> device/node ids -> presence/endpoints`.

DHT endpoint values are address hints, not authority. Cached endpoint candidates
from DHT, contact nodes, hole punching, or gossip must be treated as hints until
a qne-p2p session proves the peer identity and revocation/capability checks
pass.

Gossip is signed-record sync over qneskills carried by qne-p2p. It must not be a
separate raw transport. The minimal current gossip skill shape is
`qneskill-gossip` with `announce_inventory`, `request_records`, and
`send_records` actions. Initial record scopes include presence, role manifests,
revocations, network epochs, and artifact manifests.

The qne-p2p static public key is the intended node identity key. Presence and
revocation records should be signed by the matching static private key once the
qne-p2p crate exposes the necessary stable identity/signature API. Any qne-p2p
crate change must be referred to the founder before implementation.

## Bootstrap Download Coordination

Installer downloads are coordinated by a QNE master node before Bunny file
delivery. The master handles only the small dynamic decision: platform guess,
request IP observation, MaxMind ASN/ISP/GeoNames hints, artifact selection,
short-lived nonce creation, and bootstrap UUID creation. Bunny remains the
static large-file delivery host.

The bootstrap record is temporary until the installer claims it. Direct download
URLs should have a short expiry, and installer first-run claims should expire if
the install does not happen soon enough. When claimed, the bootstrap UUID
becomes the qne-node UUID.

A qne-node install creates only a node. Users are created later by qne-node
user-onboarding flows, and some qne-nodes will never have users. Do not create
user UUIDs, base36 user names, or `users/<base36>` actor directories as part of
base qne-node installation.

Every QNE persist root must be structurally complete from creation. Node persist
and future user persist must include the standard major parts even when a part
is initially empty or unused:

- `lmdb/`
- `ltr/`
- `secrets/`

Skills and customization may later use any of these parts. A project must not
create partial persist roots that omit standard parts merely because the current
version does not yet use them.

MaxMind ASN/ISP/GeoNames facts are bootstrap observations and routing hints.
They are useful for ISP-aware and region-aware peer selection, but they are not
identity or authority. Raw IP data must not be widely gossiped. Gossip and DHT
records may carry bounded, signed hints and endpoint candidates only when needed
for resilient discovery.

## qne-p2p Black-Box Rule

All QNE peer-to-peer transport must go through the authoritative `qne-p2p`
crate as a black-box dependency. Application behavior, including presence,
liveness, runtime upgrade coordination, Codex coordination, backup
coordination, and user/device workflows, should be represented as qneskill
messages carried by qne-p2p sessions.

Project code outside `qne-p2p` may configure, call, monitor, and persist the
results of qne-p2p sessions, but it must not create competing p2p transport
code. If a project appears to need a qne-p2p capability that the crate does not
currently expose, the required crate change must be referred to the founder
before any qne-p2p crate modification is made.

## Contact Node NAT Traversal Rule

QNE WAN/LAN reachability is contact-backed and lease-based. A node must not be
treated as fully reachable merely because its service is running or because it
sent a heartbeat to a seed.

Every capable QNE node may act as a contact node for another node. A node that
wants to be reachable selects one or more contact nodes, sends contact
heartbeats, receives observed-endpoint acknowledgements, and refreshes DHT or
presence records through those contacts.

Endpoint records are leases, not facts. They must have expiry metadata and be
retired after missed heartbeats or missed contact acknowledgements. If a node
detects its WAN endpoint changed, it should notify contact nodes immediately,
but callers must still recover by consulting fresh DHT/contact records after a
failed call.

Installers and status reports must distinguish:

- service running;
- heartbeat/contact request sent;
- seed/contact acknowledgement received;
- observed endpoint known;
- DHT presence recorded;
- direct, hole-punch, relay-needed, or not-yet-known reachability.

Until seed/contact acknowledgement exists, reports should say that connection
acknowledgement is pending or not implemented, not that the node is fully
connected.

Routed doctrine: `~/QNE-doctrine/current/QNE_Contact_Node_NAT_And_Mobile_Backup_Doctrine_V1.md`.

## Mobile Recovery And Backup Rule

Mobile is first a user recovery authority and encrypted persist backup vault,
not an always-on network node. The QNE mobile app should combine QNE UI, mobile
intents/actions, personal recovery vault, encrypted persist backup management,
and restore/migration approval.

Fixed nodes may hold full lifetime data under storage policy. Companion nodes
should not be expected to hold another user's full backup. They may hold
encrypted continuity deltas/checkpoints to cover gaps while the user's mobile is
asleep or offline, but they must not be able to decrypt those pieces.

Backup manifests must span fixed-node, mobile, companion, online, and offline
storage tiers. They should record backup-set identity, sequence/chunk hashes,
holders, latest complete sequence, retention class, restore policy, and
signatures.

Storage policy classes are:

- current;
- recent-month;
- medium-2y;
- archive-lifetime;
- mobile-critical;
- companion-continuity.

Laptop compromise must not allow deletion or corruption of all good backups.
Mobile and companion backup flows should therefore be encrypted, versioned,
append-oriented, and governed by explicit local approval for destructive pruning
or restore authority changes.

Routed doctrine: `~/QNE-doctrine/current/QNE_Contact_Node_NAT_And_Mobile_Backup_Doctrine_V1.md`.

## Codex Development Device Rule

Codex can be installed and checked by QNE automation, but Codex account sign-in
remains local and manual on each device. QNE tools must not copy, sync, back up,
or transmit Codex `auth.json`, refresh tokens, API keys, Pro credentials, or
browser login sessions.

Codex device status may be reported as:

- `missing`
- `installed-not-signed-in`
- `ready`

Status reports may record command availability and auth-file presence, but not
secret content.

## Approval Envelope Rule

Remote Codex work should use a QNE approval envelope:

- Routine read/status actions can run under narrow capability grants.
- Toolchain installation, package manager mutation, service installation, and
  network publication need explicit approval or a pre-approved qneskill policy.
- Destructive operations require local human approval unless a signed, narrow,
  revocable policy exists for that exact operation class.
- Approval requests and responses should travel as QNE messages and be persisted
  as audit records.

## qneskill Message Boundary Rule

A Codex qneskill should handle prompts, responses, action requests, action
results, and approval records as QNE messages. Many payloads may be plain
strings, but the operational boundary is still the qneskill message/action
interface.

## Developer Tool Repository Rule

Authoritative developer tool binaries are organized by platform under:

```text
~/QNE-developer/repository/tools/
  macos-arm64/
  macos-x86_64/
  linux-x86_64/
  windows-x86_64/
  source/
  legacy/
  TOOL-MANIFEST.tsv
```

Each development device should keep the full tree but use the binaries from its
own platform directory. Each platform directory must be tested on a native device
for that platform. `TOOL-MANIFEST.tsv` records platform, tool name, SHA-256,
byte size, test status, and file type.

## Authority Rule

The cleaned doctrine set must be kept in QNE encrypted online storage after
review. Local doctrine copies are working copies; online storage is the
authoritative distribution point once uploaded and verified.

The clear local doctrine working copy is `~/QNE-doctrine`. When the master rules
or current doctrine change, update `~/QNE-doctrine` first and then upload the
verified tree to QNE encrypted online storage.
