# AGENTS.md

This document defines how an **agent (human or LLM‑assisted)** should migrate the existing **WWCompanion** codebase, concepts, and behaviors into **SiteCompanion**, *without rewriting from scratch*. The migration is **patch‑style**: refactor, rename, generalize, and constrain—never invent new execution semantics.


SiteCompanion is a **tool, not a product**. It exists to remove copy/paste friction while preserving explicit user intent. Automation is restricted to **context binding only**.

---


## 0. Prime Directive (Non‑Negotiable)

**Preserve the execution model.**

> Nothing may execute without an explicit user click.


Allowed:


* Automatic **context restoration** (workspace loading on navigation)

* UI reinjection on DOM mutation (idempotent)


Forbidden:

* Auto‑execution
* Background scraping
* Inferred intent
* Heuristic task selection

Allowed (explicit exception):

* Auto‑generated or inferred selectors, but **only** when they resolve to one of the following concrete patterns:
  * `{ kind: "css"; selector: string }`
  * `{ kind: "cssAll"; selector: string; index: number }`
  * `{ kind: "textScope"; text: string }`
  * `{ kind: "anchoredCss"; anchor: { kind: "textScope"; text: string }; selector: string }`

If a change violates this, it is **out of scope**.

---

## 1. Terminology Mapping (Rename, Don’t Reimagine)

| WWCompanion | SiteCompanion | Notes                                              |
| ----------- | ------------- | -------------------------------------------------- |

| Companion   | SiteCompanion | Tool rename only                                   |
| Prompt      | Task          | **Tasks are the most basic execution unit**        |
| Quick Run   | Shortcut      | Shortcut = preconfigured run                       |
| Context     | Site Text     | Explicitly bound via paste/selection               |
| Profile     | Profile       | Same meaning, now workspace-scoped                 |
| Mode        | Env           | Execution discipline (system prompt + constraints) |

Rules:

* The constructed prompt must use **`Profile`** as the header name for user context
* The extension must **never emit `Resume` as a pipeline header or constant prompt text**
* Users may supply resume-like content, but it is always placed under the `Profile` header

Do **not** introduce new conceptual layers.


---

## 2. Core Execution Pipeline (Must Remain Intact)


The execution pipeline is stable and final:

```
Env (system prompt + discipline)
→ Profile (opaque user context)

→ Task (semantic intent template)
→ Site Text (primary extracted text)
```


Rules:

* The pipeline must **not** contain a `Resume` stage
* Prompt headers must use **exactly** these names
* **Tasks** are the most basic executable unit

* **Shortcuts** bind `(env + profile + task)`
* Shortcuts are the **only pinnable and toolbar-exposed unit**

Agents must never collapse, rename, or reorder this pipeline.


---

## 3. Workspaces (Authoritative Model)

### 3.1 Root Global Workspace

SiteCompanion introduces a **real but hidden workspace** named **`global`**.

`global` is **not a special case** in code. It is a full workspace that:

* Always exists
* Is not user-deletable
* Is never auto-switched into

`global` owns:

* Global appearance defaults

* **Global API configuration (providers, endpoints, API keys)**

* Globally scoped Envs, Profiles, Tasks
* Global Presets


Rules:

* API configuration is **global-only** and **non-inheritable**
* `global` participates in inheritance like any other workspace

### 3.2 Workspace Definition

A **Workspace is a strict namespace**, but not an ownership boundary.

A workspace references:


* Appearance overrides
* Envs
* Profiles
* Tasks
* Presets
* Sites

### 3.3 Deletion Semantics


Deleting a workspace:


* **Does not delete** any Envs, Profiles, Tasks, Presets, or Sites

* Moves all referenced items to the **`global` workspace**
* Preserves names, identities, and semantics

Deletion therefore removes a *namespace*, not data.


### 3.4 Inheritance Model (Unified)

Scopes form a strict hierarchy:


```
global → workspace → site
```

Inheritance rules:

* Inherit by default
* Items may be disabled (subtractive)
* **Override by redefinition**: defining an item with the same name shadows the inherited one
* Nearest scope wins by name


Rules:

* No merging of semantics
* No inference
* APIs / API keys do **not** inherit

### 3.5 Migration Rule

If WWCompanion has:


* Global config
* Implicit defaults
* Cross-context state

Then:

* Move capability-like config into `global`
* Move user-meaningful items into a default migrated workspace
* Remove all implicit fallback logic


### 3.3 Inheritance Model (Unified)

Scopes form a strict hierarchy:

```
global → workspace → site
```


Inheritance rules:

* Inherit by default
* Items may be disabled (subtractive)
* **Override by redefinition**: defining an item with the same name shadows the inherited one
* Nearest scope wins by name

Rules:


* No merging of semantics
* No inference
* APIs / API keys do **not** inherit

### 3.4 Migration Rule

If WWCompanion has:


* Global config
* Implicit defaults
* Cross-context state

Then:

* Move capability-like config into `global`
* Move user-meaningful items into a default migrated workspace
* Remove all implicit fallback logic

---

## 4. Env & Profile Visibility (Final Decision)

In SiteCompanion:


* **Env selector is always visible**
* **Profile selector is always visible**

Even when:


* A preset defines defaults

Visibility = inspectability.

Agents must **not** introduce read‑only, hidden, or inferred env/profile states.

---

## 5. Tasks vs Shortcuts (Critical Separation)

### 5.1 Tasks


Tasks:

* Are the **most basic execution unit**
* Define semantic intent
* Are directly runnable via **manual popup execution**
* Define a **default Environment**
* Define a **default Profile**
* Are never pinnable

When a user selects or changes a Task in the popup:

* The Environment selector must refresh to the Task’s default Environment
* The Profile selector must refresh to the Task’s default Profile


### 5.2 Shortcuts

Shortcuts:


* Are concrete, named execution shortcuts
* Bind `(env + profile + task)` explicitly
* Are executable via **one click**
* Are pinnable
* **Never appear in the popup UI**

Shortcuts exist purely as **injected-toolbar shortcuts**.


### 5.3 Manual Execution (Popup Configuration)


The popup UI allows **manual execution of Tasks** using explicit configuration.

Rules:

* The popup UI must **never list or reference shortcuts**
* Manual execution must use the **same execution pipeline** as shortcuts

* Manual execution does **not** create a shortcut unless explicitly saved by the user
* Manual execution is equivalent to WWCompanion behavior

Migration rule:


> Any WWCompanion feature that "runs" something maps either to **manual Task execution** or to a **toolbar Shortcut**.

---

## 6. Site Binding & Context Extraction

### 6.1 Site Ownership


Each site:

* Belongs to exactly **one workspace**
* Has an explicit URL matcher
* Has an explicit extraction definition
* Inherits appearance, envs, profiles, tasks, presets from its workspace (unless overridden)


### 6.2 Unknown Sites (Two Paths Only)

When encountering an unknown site, **only two paths are allowed**:

#### Path A: Popup UI (default)


1. Toolbar appears in minimal state
2. User pastes or selects a portion of page text
3. System finds the *minimum DOM scope* whose `innerText` contains the pasted text
4. User confirms or retries
5. User selects workspace
6. Site config is created


#### Path B: Settings Page (manual)

* User defines URL matcher
* User defines extraction logic explicitly


Rules:

* No fuzzy matching
* No guessing
* No background scraping


---

## 7. Automatic Behavior (Strictly Limited)

Allowed automation:


* Loading a site’s associated workspace on navigation

Disallowed automation:


* Running presets
* Selecting presets
* Modifying env/profile/task

**Context may be restored. Intent may not be inferred.**

---

## 8. UI & Interaction Rules


SiteCompanion has **three UIs**, each with a strict role boundary. Wherever applicable, UI layout, interaction patterns, and visual hierarchy must **respect WWCompanion’s existing design**.


### 8.1 UI Surfaces (Authoritative)

1. **Floating Injected Toolbar**

   * Appears on **recognized sites** only
   * Floating, injected, idempotent on DOM mutation
   * Supported positions only: four corners + bottom center
   * Contains **toolbar presets only**


2. **Extension Popup UI**

   * Primary inspection, configuration, and manual execution surface

   * Never displays presets

   * State-machine driven (see below)

3. **Settings UI**

   * Configuration and organization surface only
   * No execution affordances


---

### 8.2 Floating Toolbar (Toolbar Presets Only)


The floating toolbar:

* Displays buttons named after **all enabled presets in scope for the current site**
* Executes a preset with **one click**
* Is the **exclusive surface** from which presets may be executed

Preset aggregation order:

1. Enabled **Global Presets**
2. Enabled **Workspace Presets**

3. Enabled **Site Presets**


Rules:

* Presets must never appear in the popup UI

* Presets must never appear in settings execution paths
* Presets should be labeled as **"Toolbar Presets"** where naming clarification is needed

---

### 8.3 Popup UI – State Machine

The popup UI has **exactly three states**, and **popup state must be persisted**.

Persistence rule:

* Closing the popup **must not reset state**
* Popup state is preserved until:

  * The user performs a manual action in the popup (selection / click), or
  * The user executes a toolbar Shortcut


State transitions are therefore **explicit and durable**.

---

#### State 1: Unknown Site

Shown when a site has no saved configuration.

UI elements:

* Prompt asking the user to paste **partial text** they want SiteCompanion to extract each time

* Button: **"Try Extracting Full Text"**


---

#### State 2: Extraction Review

Entered after attempting full-text extraction.

UI elements:


* Read-only buffer showing the extracted text
* Editable field to configure the **URL match pattern** for the site
* Button: **Retry** (returns to State 1)
* Button: **Confirm** (saves the site as recognized)

Validation rules:


* URL patterns must be explicit
* **No URL pattern may be a substring of another** (conflict error)

---


#### State 3: Normal Execution

Shown for recognized sites.

Rules:

* Layout must respect WWCompanion popup design
* Allows manual configuration of env, profile, and task
* Changing the Task refreshes env/profile to Task defaults
* Allows manual execution

* **Never displays shortcuts or shortcut-derived UI**

* Adds a single, read-only line indicating the **current Workspace**

---

#### State 2: Extraction Review

Entered after attempting full-text extraction.

UI elements:

* Read-only buffer showing the extracted text
* Editable field to configure the **URL match pattern** for the site
* Button: **Retry** (returns to State 1)
* Button: **Confirm** (saves the site as recognized)

Validation rules:

* URL patterns must be explicit
* **No URL pattern may be a substring of another** (conflict error)


---

#### State 3: Normal Execution

Shown for recognized sites.

Rules:

* Layout must respect WWCompanion popup design
* Allows manual configuration of env, profile, task, and site text
* Allows manual execution

* **Never displays presets or preset-derived UI**
* Adds a single, read-only line indicating the **current Workspace**

---

### 8.4 Naming & Display Rules (UI-Wide)


* Naming conflict checking is **case-insensitive**
* Display must **preserve the original casing** of the name as entered

---

### 8.2 Floating Toolbar (Presets Only)

The floating toolbar:

* Displays buttons named after **all presets enabled for the current site**
* Executes a preset with **one click**
* Is the **exclusive surface** from which presets may be executed

Preset source order:

* Enabled **Global Presets**
* Enabled **Workspace Presets**
* Enabled **Site Presets**

Rules:

* Presets must never appear in the popup UI
* Presets must never appear in the settings execution paths

---

### 8.3 Popup UI – State Machine


The popup UI has **exactly three states**.

#### State 1: Unknown Site

Shown when a site has no saved configuration.


UI elements:


* Prompt asking the user to paste **partial text** they want SiteCompanion to extract each time
* Button: **"Try Extracting Full Text"**

---

#### State 2: Extraction Review


Entered after attempting full-text extraction.


UI elements:

* Read-only buffer showing the extracted text
* Editable field to configure the **URL match pattern**
* Button: **Retry** (returns to State 1)

* Button: **Confirm** (saves the site as recognized)

Validation rules:

* URL patterns must be explicit
* **No URL pattern may be a substring of another** (conflict error)

---


#### State 3: Normal Execution

Shown for recognized sites.

Rules:

* Layout must respect WWCompanion popup design
* Allows manual configuration of env, profile, task, and site text
* Allows manual execution
* **Never displays presets or preset-derived UI**
* Adds a single line indicating the **current Workspace**

---

### 8.4 Naming & Display Rules (UI-Wide)

* Naming conflict checking is **case-insensitive**
* Display must **preserve the original casing** of the name as entered

---

---


## 9. Preset Scope, Enablement, and Naming

### 9.1 Preset Scope Resolution

Toolbar presets shown for a site are the union of:

* Enabled **Global Presets**
* Enabled **Workspace Presets** (if applicable)
* Enabled **Site Presets** (if applicable)


### 9.2 Enablement Semantics

* Presets may exist at global, workspace, or site scope
* Lower tiers inherit enable/disable state from parents by default
* A lower-tier preset with the same name **overrides and disables** the inherited one

### 9.3 Naming Scope

Naming is scoped as:

```
Enabled Global + Enabled Workspace + Enabled Site + Module Type
```

Rules:


* Conflict detection is case-insensitive within the same module type
* Display preserves original casing

---


## 10. Motion & UX Doctrine


Structural motion only:

* Viewport‑anchored reflow (FLIP pattern)
* Item stays visually fixed; UI reflows around it

Motion is:


* Structural, not decorative
* Respectful of reduced‑motion settings


---

## 11. Engineering & UX Constraints

### 11.1 Legacy WWCompanion Adapters (Removal Mandate)

Any of the following **must be removed**, not adapted:


* Legacy config adapters

* Compatibility shims
* Auto-migration layers that preserve old semantics at runtime


Migration is **one-time and destructive** at the semantic level.


Allowed:


* Data migration scripts

* Explicit renaming / reshaping of stored config


Forbidden:

* Dual-mode logic

* Runtime branching on legacy flags


---

### 11.2 Settings UI Structure (Authoritative)

The Settings UI contains the following top-level sections:

#### 1. Global Configuration

Acts as the **configuration baseline**.

Contains:

* Global appearance (theme, toolbar positioning, auto-hide on unknown sites)
* API Keys
* API Configurations
* Expandable / foldable lists of:

  * Environments
  * Profiles
  * Tasks
  * Presets

Each configuration entry:

* Is configuration-only (no execution)
* Has an enable / disable toggle

Also includes:


* Expandable / foldable list of **sites inheriting directly from global**

---

#### 2. Workspaces


Contains a list of workspace sections (all visible in sidebar TOC; TOC supports folding).


Each workspace section contains:


* Name
* Appearance overrides (inherits from global on creation)
* API configurations shown as **enable/disable toggles only**
* Expandable / foldable lists of:

  * Environments
  * Profiles
  * Tasks
  * Presets

Each list is split into:

* **Inherited** (toggle-based enable/disable)
* **Workspace-specific** (full configuration UI)

Also includes:

* Expandable / foldable list of **sites inheriting from this workspace**

---

#### 3. Sites

Mirrors the Workspace structure, minus the list of sites.


Rules:

* Lower tiers inherit both enabled/disabled state and defaults from parents
* On creation or parent change, inherited defaults must be refreshed
* If a site/workspace config name conflicts with an enabled inherited one:

  * The inherited one is automatically disabled
  * Helper text must explain the override

---


### 11.3 Duplication Semantics

For all non-API configurations, duplication must be offered as:

* **Duplicate to Workspace** (with selector)
* **Duplicate to Site** (with selector)

No generic duplicate buttons are allowed.

---

### 11.4 Naming & Conflict Detection

Naming rules are **case-insensitive and module-specific**.


Rules:

* Conflicts are detected case-insensitively
* Display preserves original casing
* Different module types may share the same name

---

### 11.5 Error Checking & Messaging

Error checking is **mandatory and non-removable**.

Agents:

* May refactor validation logic
* May strengthen invariants
* May change *where* errors are surfaced in the UI


Agents may **not**:

* Silence errors
* Convert errors into warnings
* Auto-recover from invalid state without user action

Errors must:


* Be explicit
* Be attributable to a concrete user action or config
* Not block unrelated UI inspection

---

### 11.6 UI Design Theme

Respect the existing SiteCompanion UI doctrine:

* Minimal surface area
* WWCompanion layout parity where applicable

* No instructional text in execution paths
* No decorative UI

* No icon-first navigation

UI exists to expose state, not to explain it.

---


## 12. Migration Checklist (Agent‑Facing)

An agent migrating WWCompanion must:

* [ ] Rename concepts using the mapping table

* [ ] Ensure constructed prompts use `Profile` (never `Resume`) as the header
* [ ] Introduce workspaces as hard namespaces

* [ ] Introduce the `global` workspace for capability config
* [ ] Split global state into workspace‑owned state
* [ ] Separate tasks from presets
* [ ] Ensure only presets execute
* [ ] Make env & profile selectors always visible
* [ ] Remove any auto‑execution logic
* [ ] Remove all legacy config adapters
* [ ] Enforce case‑insensitive, module‑local naming rules

* [ ] Constrain automation to context binding only
* [ ] Keep execution pipeline intact


If any step requires inventing behavior, stop.


---

## 13. Closing Doctrine

SiteCompanion is intentionally **narrow**.


It restores **clarity of intent** by enforcing boundaries:

* Context may be bound automatically
* Intent may only cross the boundary via an explicit click

Legacy convenience is not a justification for ambiguity.


> The tool must always make it obvious *what will run*, *with what*, and *why*.

Agents exist to preserve this clarity — not to smooth it away.