chore: harden operator workflows and documentation

Author: codex

.github/workflows/ci.yml

@@ -39,7 +39,7 @@ jobs:
       - name: Replay eval proof
         run: npm run eval:replays -- --json-out artifacts/replay-overview.json
 
-      - name: Architecture surface smoke
+      - name: Review surface smoke
         run: npm run architecture:smoke -- --json-out artifacts/architecture-surface-smoke.json
 
       - name: Build

CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing to AegisOps
 
-Thanks for helping improve this project. Keep changes small, documented, and easy to architecture.
+Thanks for helping improve this project. Keep changes small, documented, and easy to review.
 
 ## Development Workflow
 
@@ -25,7 +25,7 @@ Keep the subject line under 72 characters when practical. Use the body to explai
 
 ## Quality Bar
 
-Before requesting architecture:
+Before requesting review:
 
 - Run the fastest relevant local check first.
 - Run the full test suite when touching shared logic or public behavior.

README.md

@@ -1,4 +1,4 @@
-# AegisOps -- Multimodal Incident Architecture System
+# AegisOps -- Multimodal Incident Review System
 
 [![CI](https://github.com/KIM3310/AegisOps/actions/workflows/ci.yml/badge.svg)](https://github.com/KIM3310/AegisOps/actions)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.8-blue?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
@@ -11,32 +11,32 @@
 
 1. Open the Cloudflare demo or local UI and run one incident scenario.
 2. Inspect the replay eval suite before trusting live model output.
-3. Run `npm run verify` to cover typecheck, tests, replay evals, architecture smoke, and build.
-4. Architecture export/handoff artifacts as the architecture-facing proof, not just the chat flow.
+3. Run `npm run verify` to cover typecheck, tests, replay evals, surface smoke, and build.
+4. Review export and handoff artifacts as operator-facing proof, not just the chat flow.
 
-## Product and System Surface
+## System Overview
 
 | Lens | Current answer |
 |---|---|
-| Audience | SOC, IT operations, managed service, and incident-response teams that need clearer handoff after noisy incidents. |
-| Architecture path | Validate the demo, README, architecture notes, and quality gate before deeper workflow architecture. |
-| System signal | Multimodal incident analysis, schema-conformant reports, replay evals, follow-up Q&A, and export paths. |
-| Safety boundary | Browser never receives provider keys; demo mode is deterministic and no-key by default. |
-| Fast path | `npm run verify`, live Cloudflare Pages demo, replay eval suite, and architecture smoke script. |
+| Users | SOC, IT operations, managed service, and incident-response teams that need clearer handoff after noisy incidents. |
+| Technical path | Validate the demo, README, architecture notes, and quality gate before deeper workflow review. |
+| System scope | Multimodal incident analysis, schema-conformant reports, replay evals, follow-up Q&A, and export paths. |
+| Operating boundary | Browser never receives provider keys; demo mode is deterministic and no-key by default. |
+| Evaluation path | `npm run verify`, live Cloudflare Pages demo, replay eval suite, and surface smoke script. |
 
-## System Fast Path
+## Evaluation Path
 
-- **First minute:** Open the Cloudflare demo, run one incident scenario, then inspect replay eval coverage.
+- **Start here:** Open the Cloudflare demo, run one incident scenario, then inspect replay eval coverage.
 - **Local demo:** Run `npm install && npm run dev`; the UI runs on `http://127.0.0.1:3000` and API on `http://127.0.0.1:8787`.
-- **Verification:** Run `npm run verify`; it covers typecheck, tests, replay evals, architecture smoke, and build.
+- **Checks:** Run `npm run verify`; it covers typecheck, tests, replay evals, surface smoke, and build.
 
 ## Service Launch Playbook
 
-- [Service launch playbook](docs/service-launch-playbook.md) maps the repository to architecture audiences, operating gates, operating boundaries, and risk controls.
+- [Service launch playbook](docs/service-launch-playbook.md) maps the repository to intended audiences, operating gates, operating boundaries, and risk controls.
 
 ## Architecture Notes
 
-- [Architecture guide](docs/architecture-evidence-map.md) summarizes the project angle, first files to inspect, runtime commands, and known boundaries.
+- [Architecture guide](docs/architecture-evidence-map.md) summarizes the system scope, first files to inspect, runtime commands, and known boundaries.
 - [Quality notes](docs/quality-gate.md) lists the local checks, CI surface, and release expectations for this repository.
 - [Enterprise readiness notes](docs/enterprise-readiness.md) outlines security, data, operations, integration, and handoff expectations.
 
@@ -140,7 +140,7 @@ If no API key is set, the system runs in **demo mode** -- deterministic output,
 ### Verify the build
 
 ```bash
-npm run verify   # typecheck + test + replay evals + architecture smoke + build
+npm run verify   # typecheck + test + replay evals + surface smoke + build
 ```
 
 ---
@@ -264,7 +264,7 @@ Set `GOOGLE_APPLICATION_CREDENTIALS` + `GCP_PROJECT_ID` to persist incident arti
 AegisOps/
   App.tsx                    # React app root
   types.ts                   # Shared TypeScript types
-  constants.ts               # Sample presets, architecture lenses
+  constants.ts               # Sample presets, review lenses
   components/                # React UI components (26 files)
   hooks/                     # React hooks (app state, auth, storage)
   services/                  # Frontend service clients (Google APIs, Gemini, export)
@@ -303,7 +303,7 @@ AegisOps/
 npm test                    # Unit tests (Vitest, 29 test files)
 npm run typecheck           # TypeScript strict mode check
 npm run eval:replays        # Replay eval suite (4 scenarios / 32 checks)
-npm run architecture:smoke        # Architecture surface smoke tests
+npm run architecture:smoke        # Review surface smoke tests
 npm run verify              # All of the above + build
 ```
 
@@ -335,15 +335,13 @@ Built by [Doeon Kim](https://github.com/KIM3310)
 
 ## Cloud + AI Architecture
 
-This repository includes a neutral cloud and AI engineering blueprint that maps the current proof surface to runtime boundaries, data contracts, model-risk controls, deployment posture, and validation hooks.
-
 - [Cloud + AI architecture blueprint](docs/cloud-ai-architecture.md)
 - [Machine-readable architecture manifest](docs/architecture/blueprint.json)
 - Validation command: `python3 scripts/validate_architecture_blueprint.py`
 
 ## Enterprise Productization
 
-- [Product operating model](docs/product-operating-model.md) defines the architecture inspection, trust boundary, trust boundary, operating checks, and service path for this repository.
+- [Product operating model](docs/product-operating-model.md) defines the product scope, trust boundary, operating checks, and service path for this repository.
 
 ## System Architecture
 

__tests__/AppFrontDoor.test.ts

@@ -111,7 +111,7 @@ const {
     product: {
       name: 'AegisOps',
       category: 'incident copilot',
-      headline: 'Turn logs into a inspectable incident story.',
+      headline: 'Turn logs into a reviewable incident story.',
     },
     workflow: ['collect', 'reason', 'decide'],
     runtimeModes: [],

__tests__/GeminiService.test.ts

@@ -195,7 +195,7 @@ describe("geminiService apiFetch", () => {
           product: {
             name: "AegisOps",
             category: "multimodal incident copilot",
-            headline: "Turn logs, screenshots, and alerts into a inspectable incident report.",
+            headline: "Turn logs, screenshots, and alerts into a reviewable incident report.",
           },
           workflow: ["collect", "reason", "decide", "communicate"],
           runtimeModes: [],

__tests__/OpsMetaApi.test.ts

@@ -125,7 +125,7 @@ describeIfSocketBinding("service meta endpoints", () => {
     expect(body.links.summaryPack).toBe("/api/summary-pack");
   });
 
-  it("returns a resource pack for inspection-safe incident walkthroughs", async () => {
+  it("returns a resource pack for review-safe incident walkthroughs", async () => {
     const res = await fetch(`${baseUrl}/api/resource-pack`);
     const body = await res.json();
 

components/AppHeader.tsx

@@ -128,7 +128,7 @@ export function AppHeader({ state }: AppHeaderProps) {
           </button>
           <button type="button" onClick={copyReviewStateLink} className="h-8 px-2.5 text-xs text-text-muted hover:text-text hover:bg-bg-hover rounded-md flex items-center gap-1.5 transition-colors">
             <FileText className="w-3.5 h-3.5" />
-            Copy Architecture Link
+            Copy Review Link
           </button>
         </div>
       </div>

components/FrontDoorSection.tsx

@@ -92,13 +92,13 @@ export function FrontDoorSection({ state }: FrontDoorSectionProps) {
               onClick={copyReviewChecklist}
               className="h-9 px-4 rounded-md border border-border bg-bg hover:bg-bg-hover text-sm text-text-muted hover:text-text"
             >
-              Copy Architecture Checklist
+              Copy Review Checklist
             </button>
             <button
               onClick={copyArchitectureRoutes}
               className="h-9 px-4 rounded-md border border-border bg-bg hover:bg-bg-hover text-sm text-text-muted hover:text-text"
             >
-              Copy Architecture Routes
+              Copy Review Routes
             </button>
           </div>
         </div>

components/OperatorDashboard.tsx

@@ -38,14 +38,14 @@ export function OperatorDashboard({ state }: OperatorDashboardProps) {
             Operator Dashboard
           </div>
           <p className="text-2xs text-text-muted max-w-2xl">
-            입력 전에 runtime posture, architecture flow, fast links, preset repro path를 한 번에 정리합니다.
+            입력 전에 runtime posture, review flow, fast links, preset repro path를 한 번에 정리합니다.
           </p>
         </div>
         <button
           onClick={copyReviewChecklist}
           className="h-8 px-3 rounded-md border border-border bg-bg hover:bg-bg-hover text-xs text-text-muted hover:text-text"
         >
-          Copy Architecture Checklist
+          Copy Review Checklist
         </button>
       </div>
 
@@ -54,7 +54,7 @@ export function OperatorDashboard({ state }: OperatorDashboardProps) {
           onClick={copyArchitectureRoutes}
           className="h-8 px-3 rounded-md border border-border bg-bg hover:bg-bg-hover text-xs text-text-muted hover:text-text"
         >
-          Copy Architecture Routes
+          Copy Review Routes
         </button>
         <button
           onClick={copyEvidenceSnapshot}
@@ -84,7 +84,7 @@ export function OperatorDashboard({ state }: OperatorDashboardProps) {
           onClick={copyReviewStateLink}
           className="h-8 px-3 rounded-md border border-border bg-bg hover:bg-bg-hover text-xs text-text-muted hover:text-text"
         >
-          Copy Architecture Link
+          Copy Review Link
         </button>
         <button
           onClick={copyArchitectureBundle}
@@ -125,10 +125,10 @@ export function OperatorDashboard({ state }: OperatorDashboardProps) {
 
       <div className="grid gap-3 md:grid-cols-2">
         <div className="rounded-lg border border-border bg-bg/80 p-3 space-y-2">
-          <div className="text-[11px] uppercase tracking-[0.18em] text-text-dim">Architecture flow</div>
+          <div className="text-[11px] uppercase tracking-[0.18em] text-text-dim">Review flow</div>
           <div className="space-y-2">
             {(summaryPack?.twoMinuteArchitecture?.length ? summaryPack.twoMinuteArchitecture : [
-              { step: 'Load summary pack', surface: '/api/summary-pack', proof: 'architecture route unavailable' },
+              { step: 'Load summary pack', surface: '/api/summary-pack', proof: 'review route unavailable' },
             ]).map((item) => (
               <div key={`${item.step}-${item.surface}`} className="rounded-md border border-border bg-bg-card/70 px-3 py-2">
                 <div className="text-xs font-medium text-text">{item.step}</div>
@@ -140,7 +140,7 @@ export function OperatorDashboard({ state }: OperatorDashboardProps) {
         </div>
 
         <div className="rounded-lg border border-border bg-bg/80 p-3 space-y-2">
-          <div className="text-[11px] uppercase tracking-[0.18em] text-text-dim">Fast architecture routes</div>
+          <div className="text-[11px] uppercase tracking-[0.18em] text-text-dim">Fast review routes</div>
           <div className="flex flex-wrap gap-2">
             {architectureRoutes.length > 0 ? (
               architectureRoutes.map(([label, href]) => (
@@ -155,7 +155,7 @@ export function OperatorDashboard({ state }: OperatorDashboardProps) {
                 </a>
               ))
             ) : (
-              <div className="text-2xs text-text-muted">Architecture routes are still loading.</div>
+              <div className="text-2xs text-text-muted">Review routes are still loading.</div>
             )}
           </div>
           <div className="text-2xs text-text-muted">

components/OperatorReadinessCard.tsx

@@ -84,7 +84,7 @@ function buildNextMove(props: Props) {
   if (props.health?.deployment === "static-demo") {
     return {
       title: "Prove the replay path, not live runtime",
-      summary: "This build is static-demo, so the strongest next move is analyze the current incident and then use architecture routes to explain what would change in live mode.",
+      summary: "This build is static-demo, so the strongest next move is to analyze the current incident and then use review routes to explain what would change in live mode.",
       bullets: [
         "Static demo can still prove incident structure and escalation",
         "Provider comparison is guidance, not live telemetry",