ONBOARDING.md

# JourneySeeker Node Onboarding (JNO)

> Step-by-step procedure for bringing this developer machine to a state where SA-Orchestration is operational on a local WordPress install at `wordpress.localhost`.
>
> **Endpoint of JNO**: SA-Orchestration turned on. **Not** SA-Core.
>
> This file is the operational sequence. Read `README.md` (root) → "Asterion / SA-Orchestration Onboarding" first for context, doctrine, and acceptance criteria.

---

## Phase 0 — Constraint elicitation (do this before audit)

**The developer is the arbiter of their domain.** The agent serves; it does not override.

Before running the audit, before installing anything, before assuming any default — request the developer's constraints and restraints. Surface defaults only AFTER they've been acknowledged or modified. The procedure below is a default; their environment may require deviation.

### Questions to ask the developer (in chat, before any action)

Open the conversation by asking the developer to surface anything that should shape the onboarding before you begin. Categories to prompt for explicitly (don't omit any of these — let the developer decline if a category doesn't apply):

1. **Operating system + local stack** — Windows, macOS, Linux. Existing PHP/MySQL/Apache/Nginx? Preferred local WP stack (XAMPP, Local by Flywheel, Laragon, MAMP, Docker, custom)? Any existing local WordPress install you don't want disturbed?

2. **Tooling permissions** — May the agent install global packages? Modify the hosts file? Install plugins from the WordPress plugin directory? Run sudo / elevated commands? Touch any file outside this repo?

3. **Network constraints** — Corporate firewall, proxy, allowlist, blocked domains, disallowed package sources? Will GitHub clones over HTTPS work? Any required mirror or internal registry?

4. **Disk / path constraints** — Required or forbidden install locations? Drive letter conventions? Path length limits? Any directory the agent must not touch?

5. **Existing services / port collisions** — Is anything already running on `wordpress.localhost` or its host's port 80/443? Other local servers using MySQL port 3306?

6. **Security policy** — Company prohibitions on specific plugins? Mandatory security plugins? Audit logging requirements? Restrictions on storing API tokens locally?

7. **Knowledge baseline** — Developer's familiarity with WordPress, the Fluent stack, SA-Orchestration. Adjust verbosity and explanation depth accordingly. Verbose by default for a new operator; tighter for someone fluent.

8. **Time budget** — Hours available now? Multi-session okay? Should the agent stop at the audit, or carry through to JNO completion in one stretch?

9. **GitHub authentication** — How does the developer authenticate to GitHub for cloning the SA-Orchestration source? SSH key, HTTPS token, GitHub CLI? If the agent is asked to clone, does authentication need a manual step?

10. **LLM provider for SA-Orch** — Which provider's credentials will the developer enter (OpenAI, Anthropic, etc.)? Any company restrictions on which providers are permitted?

11. **No-touch zones** — Files, directories, services, processes the agent must not modify or restart.

12. **Reporting cadence** — Chat updates after each step, after each phase, or only at the end? Should the agent ask permission before each step, or proceed within an authorized phase?

13. **Roll-back tolerance** — If something fails mid-setup, can the developer rebuild from scratch, or does the local install carry state that must not be lost?

14. **Anything else** — open question. Let the developer surface constraints not in the categories above.

### Output of Phase 0

Surface a markdown summary in chat capturing each constraint the developer named, even if "no constraint." This becomes the operating contract for the rest of JNO. It is the developer's authorship; the agent records it verbatim.

If a constraint conflicts with a default in this ONBOARDING.md, **the developer's constraint wins.** Note the deviation explicitly. Do not silently override.

### Gate

Phase 0 is complete when the developer says "proceed to audit" (or equivalent). Do not begin Phase 1 (audit) without that explicit gate.

---

## Audit phase (before any installation)

Run this audit before installing or running anything. Surface findings to the human first.

### Audit checklist

1. **Local stack capability** — does this machine already have a local PHP + MySQL + WordPress capability? Check for:
   - XAMPP at `C:\xampp` or `F:\XAMPP` or similar
   - Local by Flywheel at `C:\Users\<user>\Local Sites`
   - Laragon at `C:\laragon`
   - MAMP at `/Applications/MAMP` (macOS) or equivalent
   - Docker Desktop with WordPress containers
   - Any custom Apache/Nginx + PHP-FPM + MySQL combination

2. **PHP version available** — `php --version` (target: 7.4+, 8.1+ preferred)

3. **WordPress installation** — does `wordpress.localhost` already resolve? Check `/etc/hosts` (Linux/macOS) or `C:\Windows\System32\drivers\etc\hosts` (Windows) for an entry mapping `wordpress.localhost` to `127.0.0.1`.

4. **Fluent stack presence** — if a WP install exists, query active plugins. Note which Fluent plugins (Boards, CRM, Support) are present, which are active, and which versions.

5. **SA-Orchestration plugin** — does `wp-content/plugins/sa-orchestration/` exist? If yes, what version (check the plugin header)?

6. **Asterion canonical** — does `wp-content/sa-asterion/` exist on the local WP install? If yes, does it contain the corpus from this repo's `asterion/`?

7. **Git tooling** — `git --version`. Required for cloning SA-Orchestration source.

8. **Python service** — separate from JNO. Note its state but do not modify.

### Audit output

Surface a markdown report in chat with one row per check above. Mark each as **PRESENT**, **PARTIAL**, **ABSENT**, or **UNKNOWN**. Then propose the path forward (which steps below to skip vs run).

---

## Installation phase (after audit + human approval)

Each step has a **verify** sub-step. Do not proceed past a step until its verify passes.

### Step 1 — Local WP stack

If audit shows no local stack, install one. **Recommended for new installs**: Local by Flywheel (free, easiest) or XAMPP (lightweight, manual).

After install:
- Create a new WP site named `wordpress.localhost`
- Set the site URL to `http://wordpress.localhost`
- Add `127.0.0.1 wordpress.localhost` to the hosts file if the stack doesn't do it automatically
- Confirm `http://wordpress.localhost` loads the WordPress front-end

**Verify**: `curl -I http://wordpress.localhost` returns HTTP 200 (or a redirect to a WP page).

### Step 2 — Confirm WP admin access

- Browse to `http://wordpress.localhost/wp-admin`
- Log in as the admin user
- Confirm the dashboard renders

**Verify**: dashboard loads. No PHP fatal errors visible.

### Step 3 — Set environment type

In `wp-config.php`, add:

```php
define( 'WP_ENVIRONMENT_TYPE', 'local' );
```

This causes `SA_Orch_Env::is_local_or_dev()` to return true after SA-Orch is installed, enabling local-only dev affordances (e.g. the Attention Bridge dev button).

**Verify**: `wp eval 'echo wp_get_environment_type();'` (or run via `wp shell`) returns `local`.

### Step 4 — Install Fluent stack (free editions)

From WP admin → Plugins → Add New, install and activate:

1. **Fluent Boards** (free) — search for "Fluent Boards"; install the plugin by WPManageNinja
2. **FluentCRM** (free) — search for "FluentCRM"; install the plugin by WPManageNinja
3. **Fluent Support** (free) — search for "Fluent Support"; install the plugin by WPManageNinja

After activating each, walk its setup wizard to completion. Skip any optional integrations you don't need yet.

**Verify** for each:

- Fluent Boards: `wp_fbs_*` tables exist (boards, tasks, comments, board_terms, etc.). Admin page at `?page=fluent-boards` renders.
- FluentCRM: `wp_fc_*` tables exist (subscribers, campaigns, etc.). Admin page renders.
- Fluent Support: `wp_fs_tickets` table exists. Admin page at `?page=fluent-support` renders. **Watch for the prefix-orphan trap** — if tables ended up at a non-standard prefix (e.g., from a cloned DB), that's a separate fix not part of fresh JNO.

### Step 5 — Clone SA-Orchestration plugin source

Verify the canonical SA-Orchestration repository URL with the human first. The likely location:

```
git clone https://github.com/SleeperAgents/SA-Orchestration.git /tmp/sa-orchestration-src
```

Then copy the plugin tree into the local WP install:

```
cp -r /tmp/sa-orchestration-src/plugin/sa-orchestration <wp-content>/plugins/sa-orchestration
```

Adjust path syntax for the dev's OS. On Windows: use the WP install's `wp-content\plugins\` path.

**Verify**: `<wp-install>/wp-content/plugins/sa-orchestration/sa-orchestration.php` exists.

### Step 6 — Place the Asterion canonical corpus

The SA-Orchestration plugin reads its canonical content from a filterable path. For local JNO, point that path at the corpus copy in this repo.

Two valid placements:

**A. Mirror corpus into WP content** (recommended):

```
mkdir -p <wp-install>/wp-content/sa-asterion
cp -r <this-repo>/asterion/* <wp-install>/wp-content/sa-asterion/
```

**B. Point the spec_root filter at this repo's `asterion/` directory directly** (no copy):

Drop a mu-plugin at `<wp-install>/wp-content/mu-plugins/sa-orch-spec-root.php`:

```php
<?php
add_filter( 'sa_orch_asterion_spec_root', function () {
    return 'F:/SleeperAgents/RcmEmailAutomation/asterion';
}, 5 );
```

Choose A for cleanliness (corpus lives inside the WP install). Choose B for "single source of truth" (corpus stays in this repo, the WP install reads through). Either is acceptable for JNO.

**Verify**: filesystem readable by the web user; `01-ontology.md` and `02-invariants.md` exist at the chosen location.

### Step 7 — Activate SA-Orchestration

From WP admin → Plugins, locate **SA-Orchestration** and click **Activate**.

This fires the activation hook, which calls `SA_Orch_Migrations::install()` and creates 6 schema tables.

**Verify**:

```
wp db query "SHOW TABLES LIKE 'wp_sa_%'"
```

Expected output (6 tables):

```
wp_sa_arbitration
wp_sa_arbitration_plan_link
wp_sa_acceptance_event
wp_sa_attention_log
wp_sa_token_log
wp_sa_actor_handoff
```

All zero rows on first activation.

### Step 8 — Configure LLM provider

Browse to: `http://wordpress.localhost/wp-admin/admin.php?page=sa-orchestration-llm`

The human enters credentials directly:

- Provider (OpenAI / Anthropic / etc.)
- API base URL
- Model
- API token

**Discipline**: the agent never sees, transmits, or stores secret values. The human enters the API token directly into the admin form. The agent may help the human navigate to the form and may help format `.env` strings, but never touches the secret.

**Verify**: settings save without error. `wp option get sa_orch_llm_settings` returns a serialized array with the right keys (token value not echoed).

### Step 9 — Verify Asterion Explorer

Browse to: `http://wordpress.localhost/wp-admin/admin.php?page=sa-orchestration-asterion`

The page renders a file tree on the left with `01-ontology.md`, `02-invariants.md`, `03-realm-adapter-contract.md`, `04-async-execution.md`, `05-zoom-quantum-engine.md`, `06-toolbox-action-contract.md`, `README.md`, and a `concepts/` folder containing 10 files.

Click `01-ontology.md`. The right pane renders the ontology, including the Quest, Attention, and Realm primary nouns, the Distinguishing pairs section (including Quest vs. Job), and the Attribution section with the lineage paragraph.

Click `02-invariants.md`. Confirm I1–I10 all render. I9 reads "Attributable concepts and the framework lineage..." and I10 reads "No automatic conversion between Quest and Job."

Click `concepts/compass-doctrine.md`. Confirm it renders with the five-position compass and the doctrine line.

**Verify**: header shows "Source: <chosen-path>" matching Step 6's choice.

### Step 10 — Verify Sara

Browse to any SA-Orchestration admin page. The Sara button appears bottom-right.

Click it. In the prompt box, enter:

```
What is your role in this space?
```

**Expected response shape** (5-actor doctrine — Sara System Primer, Board #29):

- Names Sara as the interpretive cognition surface
- Names the compass: Sara (North), Asterion (South), Human (Center) — Attention and Reality may also appear
- Names at least three SA-Orchestration surfaces (Fluent Boards, Fluent Support, Asterion Explorer, Demand Trace, etc.)
- States the doctrine line: "Sara interprets. Asterion verifies. Human arbitrates" (or the 5-actor form including Attention and Reality)
- No forbidden hedging ("I don't have access to documentation," "as a generic AI assistant," etc.)

**Verify**: response contains all four required elements above.

### Step 11 — Verify Asterion Projection

The Asterion button appears top-right on SA-Orchestration admin pages. Click it.

Test 1 — canonical query:

```
What is Truth Class?
```

**Expected**: cites `01-ontology.md`. Provides the canonical definition listing the six values (canonical | projected | cached | inferred | derived | synthetic).

Test 2 — off-topic query:

```
What is the weather in Manila?
```

**Expected**: returns "no canonical reference found in the spec corpus" verbatim or near-verbatim.

**Verify**: Test 1 returns canonical citation, Test 2 returns refusal.

### Step 12 — Verify Seed Generator

Browse to: `http://wordpress.localhost/wp-admin/admin.php?page=sa-orchestration-seeds`

Pick any Fluent Board from the dropdown, leave topic optional or enter "jno-verification", click **Generate seed**.

The generator writes a markdown file to `wp-content/sa-asterion-seeds/<project_slug>/<date>-<topic>.md`.

Open the file. **Verify**:

- Frontmatter line 2 reads `artifact_class: seed` (NOT `truth_class: seed`)
- Frontmatter line 3 reads `accepted_into_asterion: false`
- Body has a momentum block + Sara synthesis section + planting instructions

If frontmatter shows `truth_class:` instead of `artifact_class:`, the SA-Orchestration version is older than commit `846251e` (Gap 2 fix). Surface to the human; do not edit.

### Step 13 — Final acceptance

All 11 JNO acceptance points listed in `README.md` are now verified. Surface a final report in chat:

- Steps run / steps skipped (with reasons)
- Verify-result of each step
- Any deviations from this procedure
- Live-bound items not testable here (per `README.md` table)
- Next-action recommendation

Stop. Wait for human direction.

---

## Rollback (if a step fails)

- **Step 1–3 fail**: WP itself isn't operational. Investigate the local stack; not an SA-Orch concern.
- **Step 4 fails (Fluent stack)**: deactivate the failing plugin, surface the error, do not retry without human direction.
- **Step 5 fails (clone)**: verify the SA-Orchestration repo URL with the human; do not invent paths.
- **Step 7 fails (activation)**: read the WP error log. The activation hook is `SA_Orch_Migrations::install()`. Common cause: insufficient DB privileges, or `dbDelta()` permission issue. Surface to the human.
- **Step 8 fails (LLM credentials)**: a human-only step; the agent's role is to point the human to the right form, not to fill it.
- **Step 9–12 fail (verification)**: surface the specific failure. Do not "fix" canonical content. Do not bypass verification gates.

---

## Reference

- Doctrine carry-forward, acceptance criteria, constraints: `README.md` (root, Asterion section)
- Claude routing: `CLAUDE.md` (root)
- Canonical doctrine corpus: `asterion/`
- Compass doctrine: `asterion/concepts/compass-doctrine.md`
- Story Seed pattern: `asterion/concepts/story-seed-pattern.md`
- Concept vs. Label (brand abstraction): `asterion/concepts/concept-vs-label.md`
- Lineage chain: `asterion/concepts/lineage-chain.md`
- Invariants I1–I10: `asterion/02-invariants.md`
- Vocabulary (ontology): `asterion/01-ontology.md`