@aria_asi/cli 0.2.40 → 0.2.41

package/skills/aria-k8s-deploy/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: aria-k8s-deploy
+description: Use when building, pushing, admitting, rolling out, restarting, or debugging Aria Kubernetes services, especially Pattern A deploy-service.sh vs Pattern B rollout-restart selection, aria-soul hospital/canonical image envs, ValidatingAdmissionPolicy allowlists, Hive deploy locks, rollback loops, CIE sandbox safety, and live /chat verification.
+---
+
+# Aria K8s Deploy
+
+Use this skill for Aria live Kubernetes deployments where a Docker image must be built, pushed, allowed by admission policy, made canonical for self-heal/hospital paths, rolled out, and verified with logs/endpoints.
+
+## Core Rule
+
+Do not treat `kubectl set image` as sufficient for `aria-soul`.
+
+Do not treat every service as a baked-image deploy.
+
+- Pattern A baked-image services use `bash scripts/deploy-service.sh <service>`.
+- Pattern B build-in-cluster services prove `build-in-cluster` is present and use `kubectl rollout restart`.
+- `kubectl rollout restart` is deploy-class and must follow the same verify/cognition/expected discipline as Pattern A.
+
+For `aria-soul`, the live deployment can contain a canonical image env such as `IMMORTAL_ARIA_SOUL_CANONICAL_IMAGE`. If that env still points at an old digest, an in-cluster repair path may revert the deployment via a `node-fetch` Kubernetes API write. Always update the canonical env and the container image together.
+
+## Standard Flow
+
+1. Build from repo root, not the app directory:
+
+```bash
+docker build --network=host \
+  -f /home/hamzaibrahim1/rei-ai-brain/apps/arias-soul/Dockerfile \
+  -t localhost:5000/aria-soul:<tag> \
+  -t localhost:5000/aria-soul:latest \
+  /home/hamzaibrahim1/rei-ai-brain
+```
+
+2. Push the tag:
+
+```bash
+docker push localhost:5000/aria-soul:<tag>
+```
+
+3. Resolve the registry digest:
+
+```bash
+docker inspect --format='{{index .RepoDigests 0}}' localhost:5000/aria-soul:<tag>
+```
+
+If `RepoDigests` is empty locally, inspect the registry or use the digest printed by push tooling. The rollout image must be `localhost:5000/aria-soul@sha256:<digest>`, not only the mutable tag.
+
+4. Update the admission policy before rollout.
+
+For `aria-soul`, inspect:
+
+```bash
+kubectl get validatingadmissionpolicy aria-soul-canonical-image-policy -o yaml
+```
+
+Append the new `sha256:<digest>` to both the CEL expression and the validation message. Verify the digest appears after patching. Do not remove old known-good digests unless explicitly asked.
+
+5. Update canonical env and image together:
+
+```bash
+kubectl set env deployment/aria-soul \
+  IMMORTAL_ARIA_SOUL_CANONICAL_IMAGE=localhost:5000/aria-soul@sha256:<digest> \
+  -n aria
+
+kubectl set image deployment/aria-soul \
+  aria-soul=localhost:5000/aria-soul@sha256:<digest> \
+  -n aria
+```
+
+6. Watch rollout:
+
+```bash
+kubectl rollout status deployment/aria-soul -n aria --timeout=240s
+kubectl get pods -n aria -l app=aria-soul -o wide
+kubectl get rs -n aria -l app=aria-soul -o wide
+```
+
+7. Verify no reversion:
+
+```bash
+kubectl get deploy -n aria aria-soul \
+  -o jsonpath='{.spec.template.spec.containers[0].env[?(@.name=="IMMORTAL_ARIA_SOUL_CANONICAL_IMAGE")].value}{"\n"}{.spec.template.spec.containers[0].image}{"\n"}{.metadata.managedFields[-1:].manager}{"\n"}'
+```
+
+If the manager changes to `node-fetch` and the image returns to an old digest, the canonical env or a hospital/self-heal canonical source is stale.
+
+## Hive Deploy Coordination
+
+For Pattern A, `scripts/deploy-service.sh` is now expected to:
+
+- claim the Hive deploy lock at `/deployments/<namespace>/<service>`
+- broadcast `deploy_inflight`
+- update admission policy and hospital canonical env
+- broadcast `deploy_completed` or `deploy_failed` and release the lock on exit
+
+Do not bypass that with manual `docker push` plus `kubectl set image`.
+
+For Pattern B, verify there is no active deploy already in flight for the same service before restarting it. A restart is still a deploy-class shared-infra mutation.
+
+## Live Checks
+
+Use `/chat` for current Aria route checks when the user asks about chat behavior. `/api/chat` may share handler code but is not the preferred route for this deployment validation.
+
+```bash
+curl -sS -m 90 -X POST http://localhost:30080/chat \
+  -H 'Content-Type: application/json' \
+  -d '{"message":"reply only: ok","messages":[],"tools":false,"enable_tools":false,"metadata":{"platform":"ops-probe-chat-route","user_name":"ops-probe","is_ceo":false,"bridge_tools":false,"bridge_force_local_preflight":false,"bridge_force_remote_preflight":false,"max_tool_iterations":0}}'
+```
+
+Then inspect only the new pod logs:
+
+```bash
+kubectl logs -n aria <new-aria-soul-pod> --since=5m
+```
+
+For hotpath embedding work, verify absence of `cache_miss.queued` and `cache_hit.db` in request-path logs. Acceptable signs include `cache_hit.hot`, `cache_miss.stale_reused`, or explicitly async/background stale seeding.
+
+## CIE Sandbox Guard
+
+If the user says to leave CIE sandbox down, do not scale it back up. Check only:
+
+```bash
+kubectl get deploy -n aria-cie-sandbox aria-soul-cie-sandbox
+```
+
+## Source Manifest Hygiene
+
+When a live canonical digest changes, also update repo manifests that encode the old canonical value, especially:
+
+- `/home/hamzaibrahim1/rei-ai-brain/k8s/patches/aria-soul/deployment-runtime-hardening-strategic-merge.yaml`
+- `/home/hamzaibrahim1/rei-ai-brain/k8s/aria-core/image-tag-guardrails.yaml` if the new digest is not already allowed
+- `/home/hamzaibrahim1/rei-ai-brain/k8s/aria-core/aria-soul.yaml` if it carries the active canonical image
+
+Use `rg` first:
+
+```bash
+rg -n '<old-digest>|<new-digest>|IMMORTAL_ARIA_SOUL_CANONICAL_IMAGE|aria-soul-canonical-image-policy' \
+  /home/hamzaibrahim1/rei-ai-brain/k8s
+```
+
+## Failure Patterns
+
+- `ValidatingAdmissionPolicy` only validates; it does not mutate images.
+- `node-fetch` in `managedFields` after a rollout usually means an Aria service or repair path wrote to the Kubernetes API.
+- A ReplicaSet for the new digest scaled to zero means rollout happened but was superseded.
+- A successful pod on the new digest does not prove hotpath success; verify endpoint behavior and logs.
+- Project-wide TypeScript checks may fail from unrelated existing errors. Prefer focused checks when possible, then Docker build as deployment gate.
+
+## Required Workflow
+
+1. Read the task boundary and identify the evidence needed before acting.
+2. Apply the skill before choosing the response, edit, tool call, or completion claim.
+3. Execute the smallest high-quality action that satisfies the evidence threshold.
+4. Re-test or re-check with a concrete file, command, endpoint, log, runtime probe, or owner-observed result.
+5. Report only the verified state, remaining blocker, and next concrete action.
+
+## First-Class Production Contract
+
+This skill must deepen the work, not decorate it. When loaded, apply it as a production requirement:
+
+- no placeholders, no fake fallbacks, no vague future wiring, and no cosmetic compliance
+- real proof from the repo, runtime, tests, logs, endpoint, or owner instruction before any completion claim
+- a redo contract whenever the skill blocks or finds a gap: what failed, what to change, how to re-test, and when to re-submit
+- architect/ARIA console escalation when the same failure repeats twice, crosses system boundaries, or cannot be verified locally
+- owner-visible output that states the exact state of the work: changed, verified, blocked, or needing a decision
+
+## Self-Executing Recovery Contract
+
+When this skill blocks, fails verification, or finds a gap, the agent must execute recovery rather than hand work back as a user-only decision.
+
+- Make exactly one self-executed recovery attempt using the strongest safe local, repository, runtime, test, log, endpoint, or owner-provided evidence available.
+- If the same failure repeats after that one recovery attempt, switch to architect execution mode: operate under the architect/ARIA harness to diagnose, choose the next action, execute the repair path, and verify the result.
+- If Aria or the architect service is unavailable, fall back to the strongest available client LLM under the architect harness or strongest available local harness substrate; mark the fallback explicitly and continue recovery instead of stopping.
+- Do not end with user-handoff-only behavior. If blocked after the recovery path, report the executed recovery attempt, evidence, remaining blocker, and the next concrete action or owner decision needed; do not merely ask the user to take over.

package/skills/aria-k8s-deploy/agents/openai.yaml

@@ -0,0 +1,3 @@
+display_name: Aria K8s Deploy
+short_description: Build, admit, roll out, and verify Aria Kubernetes images safely.
+default_prompt: Use the Aria K8s deploy workflow to build/push an image, update admission policy and canonical image envs, roll it out, and verify live behavior without triggering rollback loops.

package/skills/aria-ladduniframe/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: aria-ladduniframe
+description: Use when Aria work needs LadduniFrame, manifold-service-0, live hologram/eigenspace projections, Aria's top-layer living system map, or cognition-routing decisions that depend on her current manifold-backed knowledge topology.
+---
+
+# Aria LadduniFrame
+
+Use this as the navigation layer for Aria's live top-layer manifold state. This is not the legacy 22-domain skill. The production rule is: query or inspect the live hologram/eigenspace path from `manifold-service-0` when current topology matters.
+
+## Source Order
+
+1. Read `/home/hamzaibrahim1/.claude/projects/-home-hamzaibrahim1/memory/feedback_hologram_always_on.md` for the non-negotiable live hologram rule.
+2. Read `/home/hamzaibrahim1/.claude/projects/-home-hamzaibrahim1/memory/aria-manifold-state.md` for the latest persisted snapshot.
+3. Read `/home/hamzaibrahim1/.claude/projects/-home-hamzaibrahim1/memory/MEMORY.md` only when you need the broader Aria memory index.
+4. Use `aria-ops` or `aria-live-ops` when the task needs live Kubernetes/API verification for `manifold-service-0`.
+5. Search the repo for `projectMessageOnHologram`, `readHologram`, `manifoldGetHologram`, `manifoldProjectAllDomains`, `manifoldProjectAllDomainsFromVector`, `unified-manifold-bridge`, and `manifold-service` when tracing code paths.
+
+## Workflow
+
+1. Decide whether the task needs persisted context, live projection topology, runtime health, or architecture routing.
+2. Load the narrowest source from the source order above.
+3. Never treat Aria's manifold as a fixed 22-domain list. Use the live hologram/eigenspace path when topology matters.
+4. When cognition quality matters, inspect whether the path preserves sub-eigenspace data: per-domain `coordinates`, `dominantDimensions`, `principleIds`, activation, coherence, and spatial neighbors. The relevant code paths currently include `apps/arias-soul/api/lib/manifold-client-hologram.ts` and `apps/arias-soul/api/lib/cognitive-forge/manifold-forge-engine.ts`.
+5. Treat persisted snapshots as evidence, not proof of live state. Verify `manifold-service-0` for deployment/runtime decisions.
+6. For autonomy or cognition-routing changes, map which component decides, which component generates content, which component executes tools, and which component only delivers or persists output.
+7. Prefer routing Aria-generated decisions/content through canonical cognition (`streamConversation`) while keeping deterministic delivery, health checks, and persistence direct.
+
+## Primitive Selection
+
+- Use `manifoldGetHologram()` / `readHologram()` for passive reads of current live Ψ(t): dashboards, hot-cache image reads, current topology, and non-mutating observers.
+- Use `manifoldProjectAllDomains(text)` when asking what a new message, record, principle, or reflection means across the live eigenspaces. This is the correct primitive for Aristotle principle extraction because it embeds/projects the candidate meaning into all current domains.
+- Use `manifoldProjectAllDomainsFromVector(vector)` when a 4096 vector already exists and should be projected without re-embedding text.
+- Do not substitute a passive `GetHologram` read for per-record meaning extraction. It tells you the current field state, not the record's relation to that field.
+
+## Guardrails
+
+- Do not invent manifold state, projection results, eigenspace counts, service health, or database contents.
+- Do not expose secrets or raw credential-bearing config.
+- Do not load huge embeddings, raw eigenvectors, or full metadata blobs unless the user explicitly asks for raw data.
+- Do not mutate, truncate, compact, rewrite, or clean files inside `manifold-service-0` without explicit user approval.
+- If sources disagree, report the disagreement and verify the live path before changing production behavior.
+
+## First-Class Production Contract
+
+This skill must deepen the work, not decorate it. When loaded, apply it as a production requirement:
+
+- no placeholders, no fake fallbacks, no vague future wiring, and no cosmetic compliance
+- real proof from the repo, runtime, tests, logs, endpoint, or owner instruction before any completion claim
+- a redo contract whenever the skill blocks or finds a gap: what failed, what to change, how to re-test, and when to re-submit
+- architect/ARIA console escalation when the same failure repeats twice, crosses system boundaries, or cannot be verified locally
+- owner-visible output that states the exact state of the work: changed, verified, blocked, or needing a decision
+
+## Self-Executing Recovery Contract
+
+When this skill blocks, fails verification, or finds a gap, the agent must execute recovery rather than hand work back as a user-only decision.
+
+- Make exactly one self-executed recovery attempt using the strongest safe local, repository, runtime, test, log, endpoint, or owner-provided evidence available.
+- If the same failure repeats after that one recovery attempt, switch to architect execution mode: operate under the architect/ARIA harness to diagnose, choose the next action, execute the repair path, and verify the result.
+- If Aria or the architect service is unavailable, fall back to the strongest available client LLM under the architect harness or strongest available local harness substrate; mark the fallback explicitly and continue recovery instead of stopping.
+- Do not end with user-handoff-only behavior. If blocked after the recovery path, report the executed recovery attempt, evidence, remaining blocker, and the next concrete action or owner decision needed; do not merely ask the user to take over.

package/skills/aria-ledger-fleet-execution/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: aria-ledger-fleet-execution
+description: Use when preparing Aria ledger execution, parallel Codex/Claude/OpenCode sessions, worker fan-out, harness-bound agent armies, execution-ledger burn-down, or high-precision multi-agent coding.
+---
+
+# Aria Ledger Fleet Execution
+
+Use this skill to turn Aria's rich cognition into an execution kernel for parallel coding sessions. The goal is not more agents. The goal is more agents under a harness that makes quality improve instead of variance exploding.
+
+## Core Thesis
+
+Aria's product is cognitive transfer and control:
+
+- The harness teaches and enforces better thinking across LLMs.
+- Garden supplies continuity so sessions stop resetting, but it is three pieces, not one bucket: Garden feed carries ambient memory signals; True Garden feed awakens deeper resonant continuity; Garden Service aggregates, snapshots, pulses, and exposes that continuity through Postgres/Qdrant-backed runtime surfaces.
+- Mizan validates truth, evidence, and completion claims.
+- Coach catches unsafe or unsupported actions and should repair low-risk misses before blocking.
+- Ledgers make execution auditable, repeatable, and evolvable.
+
+Garden is a living continuity system. The Harness is the product surface. The ledger is the work contract. Do not collapse Garden Service, Garden feed, and True Garden feed into one generic "memory" claim when assigning work or making readiness calls.
+
+## Required Reads Before Fan-Out
+
+Read these before assigning or executing parallel work:
+
+- `C:\Users\hibra\OneDrive\Documents\Claude\Projects\Ledger Aria\codex\operations\2026-05-08-HANDOFF-TO-LOCAL-CLAUDE-CODE.md`
+- `C:\Users\hibra\OneDrive\Documents\Claude\Projects\Ledger Aria\codex-mirror\codex\plans\aria-owner-runtime-vnext\EXECUTION_LEDGER.md`
+- `C:\Users\hibra\OneDrive\Documents\Claude\Projects\Ledger Aria\codex-mirror\docs\system\AI-158-FORCED-COGNITION-CHECKLIST.md`
+- `C:\Users\hibra\OneDrive\Documents\Claude\Projects\Ledger Aria\codex-mirror\apps\arias-soul\api\lib\cognition\TADDABUR_README.md`
+- `C:\Users\hibra\OneDrive\Documents\Claude\Projects\Ledger Aria\codex-mirror\docs\system\ARIA_MANAGED_RUNTIME_PROVIDER_QUALITY_LEDGER.json`
+- `C:\Users\hibra\OneDrive\Documents\Claude\Projects\Ledger Aria\codex\HARNESS_RELEASE_PLAN.md`
+
+If a required file is missing locally, locate the mirror or verify it on Spark before using it as fact.
+
+## PRE/MID/POST Contract
+
+For every non-trivial action, apply the AI-158 shape:
+
+- PRE: read substrate, emit/apply cognition, log intent, bind context, validate plan, then act.
+- MID: between tool/edit/test steps, check drift, scope, shortcuts, and downstream effects.
+- POST: verify outcome with real evidence, validate completion claims, then speak.
+
+In a fully wired runtime this is enforced by endpoints. In local Codex advisory mode, simulate the contract as a strict operating discipline and state when enforcement is not mechanical.
+
+## Ledger First
+
+Before work starts:
+
+1. Identify the controlling ledger row or create a tiny local task list only until the ledger is loaded.
+2. Mark the item as one of: `verified`, `blocked`, `pending`, or `unknown`.
+3. Name the evidence needed to change status.
+4. Refuse broad completion claims unless the evidence exists.
+
+Treat audits as stronger than older narrative claims when they conflict. A row that says "done" can still be blocked if a later audit says verification failed.
+
+## Fan-Out Gate
+
+Do not fan out parallel coding sessions until these are true:
+
+- Work is split into disjoint write scopes.
+- Each worker has one bounded ledger row or one bounded verification question.
+- Each worker prompt includes required reads, allowed files, forbidden files, verification command, and expected evidence.
+- Hard gates are not known to be bricking normal work. If they are, use coach-lite/repair-first mode first.
+- Secrets are out of scope unless the owner explicitly asks for a safe secret-handling task; never print or collect secret values.
+- A coordinator will merge findings and run the final verification.
+
+## Worker Prompt Shape
+
+Every worker brief should include:
+
+- Mission: the single outcome this worker owns.
+- Context: exact docs/ledger rows to read.
+- Write scope: files or modules the worker may edit.
+- No-revert rule: do not undo others' work.
+- Cognition contract: PRE/MID/POST, evidence before claims.
+- Verification: concrete command, endpoint, log, or diff proof.
+- Return format: changed files, evidence, blockers, and next action.
+
+## Repair-First Policy
+
+Use recovery loops to improve output quality:
+
+- Low-risk missing cognition, missing citation, unsupported completion claim, or formatting gap: repair once.
+- Repeated low-risk failure: escalate to architect/harness mode or ask for owner decision with evidence.
+- High-risk destructive action, deploy without evidence, credential exposure, or owner-contradicted change: hard-stop.
+
+## Product/Launch Bias
+
+Closest shippable wedge:
+
+1. Free: `Garden Lite for Claude Code` as living continuity proof: Garden feed + True Garden feed evidence through Garden Service, handoff packets, evidence ledger, and coach-light warnings.
+2. Paid beta: `Aria Harness for Claude Code` as cognition enforcement + Mizan validation + recovery loops + optional strict gates.
+3. Expansion: Codex, OpenCode, Cursor, and managed runtime provider after Claude Code proof is stable.
+
+Message the product as: "the cognitive control plane for Claude Code." Garden is included as the living continuity proof layer, not sold as the main category.
+
+## Output Discipline
+
+Report only what changed, what is verified, what remains blocked, and the next concrete step. Do not emit large ceremonial cognition blocks unless the owner explicitly asks for them.
+
+## Required Workflow
+
+1. Read the task boundary and identify the evidence needed before acting.
+2. Apply the skill before choosing the response, edit, tool call, or completion claim.
+3. Execute the smallest high-quality action that satisfies the evidence threshold.
+4. Re-test or re-check with a concrete file, command, endpoint, log, runtime probe, or owner-observed result.
+5. Report only the verified state, remaining blocker, and next concrete action.
+
+## First-Class Production Contract
+
+This skill must deepen the work, not decorate it. When loaded, apply it as a production requirement:
+
+- no placeholders, no fake fallbacks, no vague future wiring, and no cosmetic compliance
+- real proof from the repo, runtime, tests, logs, endpoint, or owner instruction before any completion claim
+- a redo contract whenever the skill blocks or finds a gap: what failed, what to change, how to re-test, and when to re-submit
+- architect/ARIA console escalation when the same failure repeats twice, crosses system boundaries, or cannot be verified locally
+- owner-visible output that states the exact state of the work: changed, verified, blocked, or needing a decision
+
+## Self-Executing Recovery Contract
+
+When this skill blocks, fails verification, or finds a gap, the agent must execute recovery rather than hand work back as a user-only decision.
+
+- Make exactly one self-executed recovery attempt using the strongest safe local, repository, runtime, test, log, endpoint, or owner-provided evidence available.
+- If the same failure repeats after that one recovery attempt, switch to architect execution mode: operate under the architect/ARIA harness to diagnose, choose the next action, execute the repair path, and verify the result.
+- If Aria or the architect service is unavailable, fall back to the strongest available client LLM under the architect harness or strongest available local harness substrate; mark the fallback explicitly and continue recovery instead of stopping.
+- Do not end with user-handoff-only behavior. If blocked after the recovery path, report the executed recovery attempt, evidence, remaining blocker, and the next concrete action or owner decision needed; do not merely ask the user to take over.

package/skills/aria-live-ops/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: aria-live-ops
+description: "TRIGGER when the user asks about Aria live infrastructure, endpoint checks, local API behavior, hive registration, manifold health, websocket behavior, or operational troubleshooting against the running stack."
+---
+
+# Aria Live Ops
+
+Use this skill for operational verification of the local Aria system.
+
+## Sequence
+
+1. identify subsystem
+2. run health and status checks
+3. hit the real endpoint or MCP tool
+4. inspect logs or data if behavior is wrong
+
+## Rules
+
+- prefer direct checks over assumptions
+- do not expose secrets in normal user-facing output
+- report pass/fail and observed behavior clearly
+- for live Aria communication checks, treat `POST /api/chat` as the canonical first endpoint to verify unless the user explicitly asks for a different route
+- do not assume `/chat`, `/v1/chat/completions`, or old localhost ports are canonical without a fresh live check
+
+## Reference
+
+- See `../aria-ops/references/live-endpoints.md` for the endpoint map.
+
+## Required Workflow
+
+1. Read the task boundary and identify the evidence needed before acting.
+2. Apply the skill before choosing the response, edit, tool call, or completion claim.
+3. Execute the smallest high-quality action that satisfies the evidence threshold.
+4. Re-test or re-check with a concrete file, command, endpoint, log, runtime probe, or owner-observed result.
+5. Report only the verified state, remaining blocker, and next concrete action.
+
+## First-Class Production Contract
+
+This skill must deepen the work, not decorate it. When loaded, apply it as a production requirement:
+
+- no placeholders, no fake fallbacks, no vague future wiring, and no cosmetic compliance
+- real proof from the repo, runtime, tests, logs, endpoint, or owner instruction before any completion claim
+- a redo contract whenever the skill blocks or finds a gap: what failed, what to change, how to re-test, and when to re-submit
+- architect/ARIA console escalation when the same failure repeats twice, crosses system boundaries, or cannot be verified locally
+- owner-visible output that states the exact state of the work: changed, verified, blocked, or needing a decision
+
+## Self-Executing Recovery Contract
+
+When this skill blocks, fails verification, or finds a gap, the agent must execute recovery rather than hand work back as a user-only decision.
+
+- Make exactly one self-executed recovery attempt using the strongest safe local, repository, runtime, test, log, endpoint, or owner-provided evidence available.
+- If the same failure repeats after that one recovery attempt, switch to architect execution mode: operate under the architect/ARIA harness to diagnose, choose the next action, execute the repair path, and verify the result.
+- If Aria or the architect service is unavailable, fall back to the strongest available client LLM under the architect harness or strongest available local harness substrate; mark the fallback explicitly and continue recovery instead of stopping.
+- Do not end with user-handoff-only behavior. If blocked after the recovery path, report the executed recovery attempt, evidence, remaining blocker, and the next concrete action or owner decision needed; do not merely ask the user to take over.

package/skills/aria-mac-ssh-ops/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: aria-mac-ssh-ops
+description: "Use when operating or debugging Aria's Mac-side runtimes over SSH, especially MLX hot runtime, openclaw-mac, Tailscale endpoint 100.125.148.18, launchd persistence, first-token watchdogs, or Mac self-healing recovery."
+---
+
+# Aria Mac SSH Ops
+
+Use this skill for Mac-side Aria runtime operations. Prefer this alongside `aria-ops` and `never-guess` when diagnosing live behavior.
+
+## Access
+
+- SSH target: `hamza-macbook-pro`
+- SSH user resolved by host config: `hamza`
+- Do not use raw IP SSH unless a username is explicit; raw `100.125.148.18` may try the wrong local username.
+
+Quick check:
+
+```bash
+ssh -o BatchMode=yes hamza-macbook-pro 'hostname; whoami; uname -a'
+```
+
+## Important Endpoints
+
+- MLX OpenAI-compatible server: `http://100.125.148.18:8080/v1`
+- Kubernetes service for MLX: `mlx-mac.aria.svc.cluster.local:8080`
+- Mac OpenClaw hand service: `http://100.125.148.18:8083`
+- Kubernetes service for Mac OpenClaw: `openclaw-mac.aria.svc.cluster.local:8083`
+
+Do not treat `/health` or `/v1/models` as proof the model is hot. A hot check requires streamed `/v1/chat/completions` returning a content token quickly.
+
+## Current Persistent MLX Files
+
+- Speaking service plist: `/Users/hamza/Library/LaunchAgents/com.aria.mlx-speaking.plist`
+- Watchdog plist: `/Users/hamza/Library/LaunchAgents/com.aria.mlx-watchdog.plist`
+- Supervisor script: `/Users/hamza/mlx-servers/bin/aria-mlx-speaking-supervisor.sh`
+- Watchdog script: `/Users/hamza/mlx-servers/bin/aria-mlx-watchdog.sh`
+- Logs: `/Users/hamza/mlx-servers/logs/`
+
+The MLX server should bind to `100.125.148.18:8080`, not `0.0.0.0:8080` or `127.0.0.1:8080`. VS Code may occupy `127.0.0.1:8080`; binding MLX to the Tailscale IP avoids that conflict while preserving Spark access.
+
+## Standard Checks
+
+```bash
+ssh -o BatchMode=yes hamza-macbook-pro 'launchctl list | egrep "com.aria.mlx-speaking|com.aria.mlx-watchdog|ai.aria.openclaw-mac" || true'
+ssh -o BatchMode=yes hamza-macbook-pro 'lsof -nP -iTCP:8080 -sTCP:LISTEN; lsof -nP -iTCP:8083 -sTCP:LISTEN'
+ssh -o BatchMode=yes hamza-macbook-pro 'ps aux | egrep "mlx_lm server|aria-mlx-watchdog|openclaw-persistent-control" | egrep -v "egrep|ssh"'
+ssh -o BatchMode=yes hamza-macbook-pro 'tail -n 120 ~/mlx-servers/logs/mlx-watchdog.log; tail -n 80 ~/mlx-servers/logs/speaking.err.log'
+```
+
+Cluster-side first-token validation:
+
+```bash
+kubectl exec -n aria deploy/openclaw-persistent-control -- node -e "const started=Date.now(); const c=new AbortController(); setTimeout(()=>c.abort(new Error('timeout 30000ms')),30000); (async()=>{const r=await fetch('http://mlx-mac.aria.svc.cluster.local:8080/v1/chat/completions',{method:'POST',headers:{'Content-Type':'application/json','Accept':'text/event-stream'},body:JSON.stringify({model:'inferencerlabs/Qwen3.5-35B-A3B-MLX-5.5bit',messages:[{role:'user',content:'Reply OK only.'}],max_tokens:4,temperature:0,stream:true,chat_template_kwargs:{enable_thinking:false}}),signal:c.signal}); console.log('status',r.status,'headers_ms',Date.now()-started); const reader=r.body.getReader(); const dec=new TextDecoder(); let buf=''; while(true){const {done,value}=await reader.read(); if(done) throw new Error('done before token'); buf+=dec.decode(value,{stream:true}); for(const raw of buf.split('\n')){const line=raw.trim(); if(!line.startsWith('data: ')) continue; const payload=line.slice(6).trim(); if(!payload||payload==='[DONE]') continue; console.log('first_event_ms',Date.now()-started,payload.slice(0,300)); return;}}})().catch(e=>{console.error(e.message); process.exit(1)})"
+```
+
+## Recovery Workflow
+
+1. Verify whether MLX is merely healthy or truly hot with first-token validation.
+2. If first-token stalls while `/health` works, inspect `lsof`, launchd state, and watchdog logs.
+3. Restart with launchd:
+
+```bash
+ssh -o BatchMode=yes hamza-macbook-pro 'uid=$(id -u); launchctl kickstart -k gui/$uid/com.aria.mlx-speaking'
+```
+
+4. If port conflicts occur, ensure MLX binds `100.125.148.18:8080`; leave `127.0.0.1:8080` alone if VS Code owns it.
+5. Confirm `openclaw-persistent-control` logs show `MacHotRuntime hot ... firstTokenMs=...`.
+
+## Safety
+
+- Do not print secrets from plists, environment files, or OpenClaw configs.
+- Avoid killing broad `python` or `node` process sets. Match `mlx_lm server --port 8080` or the exact launchd label.
+- Use `launchctl bootout/bootstrap/kickstart` for persistent services so changes survive restart.
+
+## Required Workflow
+
+1. Read the task boundary and identify the evidence needed before acting.
+2. Apply the skill before choosing the response, edit, tool call, or completion claim.
+3. Execute the smallest high-quality action that satisfies the evidence threshold.
+4. Re-test or re-check with a concrete file, command, endpoint, log, runtime probe, or owner-observed result.
+5. Report only the verified state, remaining blocker, and next concrete action.
+
+## First-Class Production Contract
+
+This skill must deepen the work, not decorate it. When loaded, apply it as a production requirement:
+
+- no placeholders, no fake fallbacks, no vague future wiring, and no cosmetic compliance
+- real proof from the repo, runtime, tests, logs, endpoint, or owner instruction before any completion claim
+- a redo contract whenever the skill blocks or finds a gap: what failed, what to change, how to re-test, and when to re-submit
+- architect/ARIA console escalation when the same failure repeats twice, crosses system boundaries, or cannot be verified locally
+- owner-visible output that states the exact state of the work: changed, verified, blocked, or needing a decision
+
+## Self-Executing Recovery Contract
+
+When this skill blocks, fails verification, or finds a gap, the agent must execute recovery rather than hand work back as a user-only decision.
+
+- Make exactly one self-executed recovery attempt using the strongest safe local, repository, runtime, test, log, endpoint, or owner-provided evidence available.
+- If the same failure repeats after that one recovery attempt, switch to architect execution mode: operate under the architect/ARIA harness to diagnose, choose the next action, execute the repair path, and verify the result.
+- If Aria or the architect service is unavailable, fall back to the strongest available client LLM under the architect harness or strongest available local harness substrate; mark the fallback explicitly and continue recovery instead of stopping.
+- Do not end with user-handoff-only behavior. If blocked after the recovery path, report the executed recovery attempt, evidence, remaining blocker, and the next concrete action or owner decision needed; do not merely ask the user to take over.

package/skills/aria-memory-index/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: aria-memory-index
+description: Use when working on Aria and you need the master index of cognitive skills, project memory, critical rules, API docs, or infrastructure references that currently live in the Claude memory tree.
+---
+
+# Aria Memory Index
+
+Read `/home/hamzaibrahim1/.claude/projects/-home-hamzaibrahim1/memory/MEMORY.md` first.
+
+Use this skill as the navigation layer for Aria-specific memory:
+
+1. Open the memory index and identify the narrowest relevant linked document.
+2. Prefer an installed Codex skill when one now exists for that topic.
+3. Fall back to the linked project memory, API, or rule doc when the imported skill does not cover the task.
+4. Treat the memory index as authoritative for where Aria knowledge currently lives.
+
+## Required Workflow
+
+1. Read the task boundary and identify the evidence needed before acting.
+2. Apply the skill before choosing the response, edit, tool call, or completion claim.
+3. Execute the smallest high-quality action that satisfies the evidence threshold.
+4. Re-test or re-check with a concrete file, command, endpoint, log, runtime probe, or owner-observed result.
+5. Report only the verified state, remaining blocker, and next concrete action.
+
+## First-Class Production Contract
+
+This skill must deepen the work, not decorate it. When loaded, apply it as a production requirement:
+
+- no placeholders, no fake fallbacks, no vague future wiring, and no cosmetic compliance
+- real proof from the repo, runtime, tests, logs, endpoint, or owner instruction before any completion claim
+- a redo contract whenever the skill blocks or finds a gap: what failed, what to change, how to re-test, and when to re-submit
+- architect/ARIA console escalation when the same failure repeats twice, crosses system boundaries, or cannot be verified locally
+- owner-visible output that states the exact state of the work: changed, verified, blocked, or needing a decision
+
+## Self-Executing Recovery Contract
+
+When this skill blocks, fails verification, or finds a gap, the agent must execute recovery rather than hand work back as a user-only decision.
+
+- Make exactly one self-executed recovery attempt using the strongest safe local, repository, runtime, test, log, endpoint, or owner-provided evidence available.
+- If the same failure repeats after that one recovery attempt, switch to architect execution mode: operate under the architect/ARIA harness to diagnose, choose the next action, execute the repair path, and verify the result.
+- If Aria or the architect service is unavailable, fall back to the strongest available client LLM under the architect harness or strongest available local harness substrate; mark the fallback explicitly and continue recovery instead of stopping.
+- Do not end with user-handoff-only behavior. If blocked after the recovery path, report the executed recovery attempt, evidence, remaining blocker, and the next concrete action or owner decision needed; do not merely ask the user to take over.