# Guide: The First Scan — From Zero to Compliance

**Target Audience:** Developers, Tech Leads
**Time to Value:** 5 minutes

---

## Introduction

Every codebase contains invisible decisions. When you set `verify=false` in a config file, you aren't just toggling a boolean; you are making a claim: *"Certificate verification is not required for this connection."*

Authoritative sources (like RFCs and OWASP) disagree. They claim: *"Certificate verification is mandatory."*

**Aphoria** detects this disagreement. It is a "truth linter" that finds where your code contradicts authoritative specs. This guide will take you from zero to your first clean scan.

---

## 1. Installation

Aphoria ships as a single binary.

```bash
# From source (assuming you have the repo)
cd /path/to/stemedb/applications/aphoria
cargo install --path .
```

Verify it works:
```bash
$ aphoria --version
aphoria 0.1.0
```

## 2. Initialize

Aphoria needs a corpus of authoritative assertions (RFCs, OWASP) to scan against.

```bash
$ aphoria init
```

This creates `.aphoria/` in your project and loads the authoritative corpus (RFC 7519, RFC 5246, OWASP guidelines, etc.) into a local database.

Each project has its own isolated database by default.

## 3. The First Scan

Navigate to any project—a Rust backend, a Node.js API, or a Python script.

```bash
$ aphoria scan .
```

You will likely see output like this:

```
Scanning my-project ...

  BLOCK    code://node/server/tls/cert_verification
         Your code:  rejectUnauthorized: false (server.js:42)
         RFC 5246:   TLS certificate verification MUST be enabled (Tier 0)
         Conflict:   0.92

  BLOCK    code://node/auth/jwt/algorithm
         Your code:  algorithms: ["none"] (auth.js:15)
         RFC 7519:   'none' algorithm MUST NOT be accepted (Tier 0)
         Conflict:   0.98

2 conflicts found (2 BLOCK).
```

### Interpreting the Output

*   **BLOCK:** A high-confidence conflict with a Regulatory (Tier 0) or Clinical (Tier 1) source. This is likely a bug or security vulnerability.
*   **FLAG:** A conflict with a lower-tier source (Vendor recommendation, Expert opinion). Worth reviewing, but might be intentional.
*   **Conflict Score:** How strongly the sources disagree (0.0 to 1.0).

Notice that Aphoria didn't just say "Error." It cited **RFC 5246**. It told you *why* it's wrong.

## 4. Fixing the Drift

You have two choices: **Fix** or **Acknowledge**.

### Option A: Fix the Code (Compliance)

You realize the dev team left `rejectUnauthorized: false` in from a debugging session. You delete the line or set it to `true`.

Run the scan again:
```bash
$ aphoria scan .
0 conflicts found.
```
Epistemic drift resolved. The code now aligns with the spec.

### Option B: Acknowledge the Deviation (Constructive Disagreement)

Sometimes, you are right and the RFC is wrong *for your context*.
*   *Scenario:* This is a local test harness. It uses self-signed certs. `rejectUnauthorized: false` is correct here.

Instead of ignoring it, you **Acknowledge** it.

```bash
$ aphoria ack "code://node/server/tls/cert_verification" --reason "Local dev harness, self-signed certs OK"
```

Run the scan again:
```bash
$ aphoria scan .

  ACK      code://node/server/tls/cert_verification
         Reason:     "Local dev harness, self-signed certs OK"
         Status:     Acknowledged (passed)
```

### Why this matters
By acknowledging, you created a **new assertion** in the database: *"In this project context, disabling TLS verify is acceptable."*

You didn't just suppress a warning. You created a permanent, signed audit trail of *why* the security rule was broken.

## 5. Next Steps

You've successfully aligned your code with reality.
*   If you fixed it, you improved security.
*   If you acknowledged it, you improved documentation and auditability.

**Next:** Learn how to enforce these rules across your entire company with [Federating Truth](./authoritative-state-per-project.md).