refira-cli 0.2.0 → 0.2.1

package/README.md

@@ -86,31 +86,40 @@ refira context
 ### 4. Page Scaffolding
 
 #### `refira scaffold`
-Generates a standalone HTML5 starter template pre-configured with:
+Generates a clean HTML5 starter template pre-configured with:
 - Google Fonts specified in project design tokens.
 - Tailwind CSS CDN and theme extensions.
 - Lucide Icons script.
 - Body content slot marking where agent layout markup should be placed.
+- Optional binding to an existing shared layout (`--layout`).
 
 ```bash
+# Scaffold standalone page
 refira scaffold --page checkout
+
+# Scaffold page bound to a shared layout template
+refira scaffold --page analytics --layout dashboard
 ```
 
 Options:
 - `--page <slug>`: Required page slug (e.g., `checkout`, `dashboard`, `landing`).
+- `--layout <slug>`: Optional layout slug to bind page to a shared layout.
 - `--output <path>`: Custom destination file path (default: `<slug>.html`).
 
 ---
 
-### 5. Live Preview, Push & Harness Validation
+### 5. Live Preview, Push & Concurrency Guard
 
 #### `refira push` (or `refira preview`)
-Inspects an HTML markup file using the Refira Agent Harness. If violations are detected, execution halts with Exit Code 1 and actionable remediation instructions. If valid, the markup is streamed directly to the Refira Canvas.
+Inspects an HTML markup file using the Refira Agent Harness. If violations are detected, execution halts with Exit Code 1 and actionable remediation instructions. If valid, the markup is streamed directly to the Refira Canvas. Supports Optimistic Concurrency Control (OCC) to prevent conflicting agent edits.
 
 ```bash
 refira push checkout.html --page checkout
 # Alternatively:
 refira preview checkout.html --page checkout
+
+# With optimistic concurrency guard:
+refira push dashboard.html --page dashboard --expected-revision a1b2c3...
 ```
 
 Arguments:
@@ -118,10 +127,106 @@ Arguments:
 
 Options:
 - `--page <slug>`: Target page slug.
+- `--expected-revision <hash>`: Expected SHA-256 revision hash for OCC concurrency guard.
+
+---
+
+### 6. Canvas Annotations & Revision Loops
+
+#### `refira annotations`
+Fetches unresolved canvas feedback annotations made by reviewers directly on the canvas elements, allowing agents to perform targeted design iterations.
+
+```bash
+refira annotations --page checkout
+refira annotations --page checkout --format json
+```
+
+Options:
+- `--page <slug>`: Required page slug or ID.
+- `--format <format>`: Output format: `table`, `json`, or `md` (default: `table`).
+
+---
+
+### 7. Layout Focus Management
+
+#### `refira layout select`
+Sets the active layout focus for the current project.
+
+```bash
+refira layout select dashboard
+```
+
+#### `refira layout status`
+Displays the current active layout focus and lists all available layouts with their archetype definitions.
+
+```bash
+refira layout status
+```
+
+---
+
+### 8. Reusable HTML Macro Components
+
+#### `refira component add`
+Registers a new reusable HTML macro component in the project catalog.
+
+```bash
+# Register from an HTML snippet file
+refira component add navbar ./components/navbar.html --tags header,nav
+
+# Register from inline HTML markup
+refira component add cta-button "<button class=\"px-4 py-2 bg-primary text-white rounded-md\">Get Started</button>" --tags button,cta
+```
+
+Options:
+- `--tags <tags>`: Comma-separated tags (e.g. `header,navigation`).
+- `--project-id <id>`: Target project UUID.
+
+#### `refira component list`
+Lists all reusable components registered in the project catalog.
+
+```bash
+refira component list
+```
+
+---
+
+### 9. JIT Interaction Pattern Guides
+
+#### `refira guide`
+Displays Just-In-Time (JIT) HTML5 + Tailwind implementation guidance for complex interaction patterns.
+
+```bash
+refira guide aria
+refira guide forms
+refira guide modals
+refira guide tables
+refira guide components
+```
+
+Topics available: `aria`, `forms`, `modals`, `tables`, `components`.
+
+---
+
+### 10. Workspace Maintenance
+
+#### `refira clean`
+Cleans up local agent work directories and scratch files (`.refira-work/`, temporary exports).
+
+```bash
+# Clean local scratch files
+refira clean
+
+# Dry run (inspect what would be removed)
+refira clean --dry-run
+
+# Clean local scratch and purge server expired tokens
+refira clean --all
+```
 
 ---
 
-### 6. Agent Skill Installation
+### 11. Agent Skill Installation
 
 #### `refira skill install`
 Installs the Refira design craftsmanship guide (`SKILL.md`) for AI agents.