novahiz 0.1.0

package/bundled-skills/mcp-server-builder/scripts/openapi_to_mcp.py

@@ -0,0 +1,284 @@
+#!/usr/bin/env python3
+"""Generate MCP scaffold files from an OpenAPI specification.
+
+Input sources:
+- --input <file>
+- stdin (JSON or YAML when PyYAML is available)
+
+Output:
+- tool_manifest.json
+- server.py or server.ts scaffold
+- summary in text/json
+"""
+
+import argparse
+import json
+import re
+import sys
+from dataclasses import dataclass, asdict
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+
+HTTP_METHODS = {"get", "post", "put", "patch", "delete"}
+
+
+class CLIError(Exception):
+    """Raised for expected CLI failures."""
+
+
+@dataclass
+class GenerationSummary:
+    server_name: str
+    language: str
+    operations_total: int
+    tools_generated: int
+    output_dir: str
+    manifest_path: str
+    scaffold_path: str
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Generate MCP server scaffold from OpenAPI.")
+    parser.add_argument("--input", help="OpenAPI file path (JSON or YAML). If omitted, reads from stdin.")
+    parser.add_argument("--server-name", required=True, help="MCP server name.")
+    parser.add_argument("--language", choices=["python", "typescript"], default="python", help="Scaffold language.")
+    parser.add_argument("--output-dir", default=".", help="Directory to write generated files.")
+    parser.add_argument("--format", choices=["text", "json"], default="text", help="Output format.")
+    return parser.parse_args()
+
+
+def load_raw_input(input_path: Optional[str]) -> str:
+    if input_path:
+        try:
+            return Path(input_path).read_text(encoding="utf-8")
+        except Exception as exc:
+            raise CLIError(f"Failed to read --input file: {exc}") from exc
+
+    if sys.stdin.isatty():
+        raise CLIError("No input provided. Use --input <spec-file> or pipe OpenAPI via stdin.")
+
+    data = sys.stdin.read().strip()
+    if not data:
+        raise CLIError("Stdin was provided but empty.")
+    return data
+
+
+def parse_openapi(raw: str) -> Dict[str, Any]:
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError:
+        try:
+            import yaml  # type: ignore
+
+            parsed = yaml.safe_load(raw)
+            if not isinstance(parsed, dict):
+                raise CLIError("YAML OpenAPI did not parse into an object.")
+            return parsed
+        except ImportError as exc:
+            raise CLIError("Input is not valid JSON and PyYAML is unavailable for YAML parsing.") from exc
+        except Exception as exc:
+            raise CLIError(f"Failed to parse OpenAPI input: {exc}") from exc
+
+
+def sanitize_tool_name(name: str) -> str:
+    cleaned = re.sub(r"[^a-zA-Z0-9_]+", "_", name).strip("_")
+    cleaned = re.sub(r"_+", "_", cleaned)
+    return cleaned.lower() or "unnamed_tool"
+
+
+def schema_from_parameter(param: Dict[str, Any]) -> Dict[str, Any]:
+    schema = param.get("schema", {})
+    if not isinstance(schema, dict):
+        schema = {}
+    out = {
+        "type": schema.get("type", "string"),
+        "description": param.get("description", ""),
+    }
+    if "enum" in schema:
+        out["enum"] = schema["enum"]
+    return out
+
+
+def extract_tools(spec: Dict[str, Any]) -> List[Dict[str, Any]]:
+    paths = spec.get("paths", {})
+    if not isinstance(paths, dict):
+        raise CLIError("OpenAPI spec missing valid 'paths' object.")
+
+    tools = []
+    for path, methods in paths.items():
+        if not isinstance(methods, dict):
+            continue
+        for method, operation in methods.items():
+            method_l = str(method).lower()
+            if method_l not in HTTP_METHODS or not isinstance(operation, dict):
+                continue
+
+            op_id = operation.get("operationId")
+            if op_id:
+                name = sanitize_tool_name(str(op_id))
+            else:
+                name = sanitize_tool_name(f"{method_l}_{path}")
+
+            description = str(operation.get("summary") or operation.get("description") or f"{method_l.upper()} {path}")
+            properties: Dict[str, Any] = {}
+            required: List[str] = []
+
+            for param in operation.get("parameters", []):
+                if not isinstance(param, dict):
+                    continue
+                pname = str(param.get("name", "")).strip()
+                if not pname:
+                    continue
+                properties[pname] = schema_from_parameter(param)
+                if bool(param.get("required")):
+                    required.append(pname)
+
+            request_body = operation.get("requestBody", {})
+            if isinstance(request_body, dict):
+                content = request_body.get("content", {})
+                if isinstance(content, dict):
+                    app_json = content.get("application/json", {})
+                    if isinstance(app_json, dict):
+                        schema = app_json.get("schema", {})
+                        if isinstance(schema, dict) and schema.get("type") == "object":
+                            rb_props = schema.get("properties", {})
+                            if isinstance(rb_props, dict):
+                                for key, val in rb_props.items():
+                                    if isinstance(val, dict):
+                                        properties[key] = val
+                            rb_required = schema.get("required", [])
+                            if isinstance(rb_required, list):
+                                required.extend([str(x) for x in rb_required])
+
+            tool = {
+                "name": name,
+                "description": description,
+                "inputSchema": {
+                    "type": "object",
+                    "properties": properties,
+                    "required": sorted(set(required)),
+                },
+                "x-openapi": {"path": path, "method": method_l},
+            }
+            tools.append(tool)
+
+    return tools
+
+
+def python_scaffold(server_name: str, tools: List[Dict[str, Any]]) -> str:
+    handlers = []
+    for tool in tools:
+        fname = sanitize_tool_name(tool["name"])
+        handlers.append(
+            f"@mcp.tool()\ndef {fname}(input: dict) -> dict:\n"
+            f"    \"\"\"{tool['description']}\"\"\"\n"
+            f"    return {{\"tool\": \"{tool['name']}\", \"status\": \"todo\", \"input\": input}}\n"
+        )
+
+    return "\n".join(
+        [
+            "#!/usr/bin/env python3",
+            '"""Generated MCP server scaffold."""',
+            "",
+            "from fastmcp import FastMCP",
+            "",
+            f"mcp = FastMCP(name={server_name!r})",
+            "",
+            *handlers,
+            "",
+            "if __name__ == '__main__':",
+            "    mcp.run()",
+            "",
+        ]
+    )
+
+
+def typescript_scaffold(server_name: str, tools: List[Dict[str, Any]]) -> str:
+    registrations = []
+    for tool in tools:
+        const_name = sanitize_tool_name(tool["name"])
+        registrations.append(
+            "server.tool(\n"
+            f"  '{tool['name']}',\n"
+            f"  '{tool['description']}',\n"
+            "  async (input) => ({\n"
+            f"    content: [{{ type: 'text', text: JSON.stringify({{ tool: '{const_name}', status: 'todo', input }}) }}],\n"
+            "  })\n"
+            ");"
+        )
+
+    return "\n".join(
+        [
+            "// Generated MCP server scaffold",
+            "import { FastMCP } from 'fastmcp';",
+            "",
+            f"const server = new FastMCP({{ name: '{server_name}' }});",
+            "",
+            *registrations,
+            "",
+            "server.run();",
+            "",
+        ]
+    )
+
+
+def write_outputs(server_name: str, language: str, output_dir: Path, tools: List[Dict[str, Any]]) -> GenerationSummary:
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    manifest_path = output_dir / "tool_manifest.json"
+    manifest = {"server": server_name, "tools": tools}
+    manifest_path.write_text(json.dumps(manifest, indent=2), encoding="utf-8")
+
+    if language == "python":
+        scaffold_path = output_dir / "server.py"
+        scaffold_path.write_text(python_scaffold(server_name, tools), encoding="utf-8")
+    else:
+        scaffold_path = output_dir / "server.ts"
+        scaffold_path.write_text(typescript_scaffold(server_name, tools), encoding="utf-8")
+
+    return GenerationSummary(
+        server_name=server_name,
+        language=language,
+        operations_total=len(tools),
+        tools_generated=len(tools),
+        output_dir=str(output_dir.resolve()),
+        manifest_path=str(manifest_path.resolve()),
+        scaffold_path=str(scaffold_path.resolve()),
+    )
+
+
+def main() -> int:
+    args = parse_args()
+    raw = load_raw_input(args.input)
+    spec = parse_openapi(raw)
+    tools = extract_tools(spec)
+    if not tools:
+        raise CLIError("No operations discovered in OpenAPI paths.")
+
+    summary = write_outputs(
+        server_name=args.server_name,
+        language=args.language,
+        output_dir=Path(args.output_dir),
+        tools=tools,
+    )
+
+    if args.format == "json":
+        print(json.dumps(asdict(summary), indent=2))
+    else:
+        print("MCP scaffold generated")
+        print(f"- server: {summary.server_name}")
+        print(f"- language: {summary.language}")
+        print(f"- tools: {summary.tools_generated}")
+        print(f"- manifest: {summary.manifest_path}")
+        print(f"- scaffold: {summary.scaffold_path}")
+
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        raise SystemExit(main())
+    except CLIError as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        raise SystemExit(2)

package/bundled-skills/memory/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: memory
+description: Alias de novahiz-memory (sauvegarde Dual-Write du contexte)
+---
+
+# Alias
+
+La sauvegarde Dual-Write est définie une seule fois dans la skill `novahiz-memory`.
+
+Charger `novahiz-memory` plutôt que d'appliquer une logique propre ici : elle écrit le `MEMORY.md` du projet, puis la page correspondante du vault Obsidian via `memory-save`.

package/bundled-skills/memory-bridge/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: memory-bridge
+description: >
+  Browse and compare wiki knowledge by which AI tool originally produced it. Use this skill when the user
+  says "/memory-bridge", "browse codex memory", "what did codex know about X", "show me claude knowledge",
+  "cross-tool memory", "what does hermes know that claude doesn't", "show me knowledge from <tool>",
+  "compare my AI tool memories", or wants to explore knowledge gaps between tools. Works from any project.
+  Diff mode ("what's different", "unique to codex", "gaps between tools") is the killer feature — it surfaces
+  blind spots between tools that the user may not know exist.
+---
+
+# Memory Bridge — Cross-Tool Knowledge Browser
+
+You are helping the user browse and compare their Obsidian wiki knowledge filtered by which AI tool originally produced it. The wiki tracks source provenance in `.manifest.json` and page `sources:` frontmatter — this skill surfaces that metadata as a navigable view.
+
+## Before You Start
+
+1. **Resolve config** — follow the Config Resolution Protocol in `llm-wiki/SKILL.md` (inline `@name` override → walk up CWD for `.env` → global config → prompt setup). This gives `OBSIDIAN_VAULT_PATH`.
+2. Read `$OBSIDIAN_VAULT_PATH/.manifest.json` — this is the source-of-truth for what tool produced what.
+3. Read `$OBSIDIAN_VAULT_PATH/index.md` for page titles and one-line descriptions.
+
+## Commands
+
+Parse the user's invocation to determine mode:
+
+| Invocation | Mode |
+|---|---|
+| `/memory-bridge <tool>` | **Browse** — list all wiki pages sourced from `<tool>` |
+| `/memory-bridge <tool> "<topic>"` | **Search** — pages from `<tool>` that mention `<topic>` |
+| `/memory-bridge diff` | **Diff** — pages unique to each tool; overlap; blind spots |
+| `/memory-bridge diff <tool-a> <tool-b>` | **Diff** — compare two specific tools |
+| `/memory-bridge map` | **Map** — full origin matrix: every page × every tool that touched it |
+
+Recognized tool names: `claude`, `codex`, `hermes`, `openclaw`, `copilot`, `pi`, `manual` (hand-written), `ingest` (wiki-ingest documents).
+
+## Step 1: Build the Source Map
+
+Read `.manifest.json`. For each source entry, extract:
+- `source_type` — maps to tool name:
+  - `claude_conversation`, `claude_memory`, `claude_audit_log`, `claude_desktop_session` → `claude`
+  - `codex_rollout`, `codex_index`, `codex_history` → `codex`
+  - `hermes_memory`, `hermes_session` → `hermes`
+  - `openclaw_memory`, `openclaw_daily_note`, `openclaw_session`, `openclaw_dreams` → `openclaw`
+  - `copilot_session`, `copilot_checkpoint`, `copilot_transcript`, `copilot_memory_artifact` → `copilot`
+  - `pi_session` → `pi`
+  - `document` → `ingest`
+  - anything else → `manual`
+- `pages_created` and `pages_updated` — the wiki pages that came out of this source
+
+Build a map:
+
+```
+tool_pages = {
+  "claude": set(pages created/updated by claude sources),
+  "codex":  set(pages created/updated by codex sources),
+  ...
+}
+```
+
+A page can appear in multiple tools' sets if multiple tools contributed to it.
+
+## Step 2: Execute the Mode
+
+### Browse Mode
+
+Filter `tool_pages[<tool>]` and present as a grouped list:
+
+```
+## Knowledge from <tool> (<N> pages)
+
+### By category
+- concepts/ — N pages
+- entities/ — N pages
+- skills/   — N pages
+...
+
+### Pages
+| Page | Category | Tags | Last updated |
+|------|----------|------|--------------|
+| [[page-name]] | concept | tag1, tag2 | 2026-04-10 |
+...
+```
+
+Read frontmatter for the listed pages (grep for `^(title|category|tags|updated):`) — do not read full page bodies unless the user asks.
+
+### Search Mode
+
+Within the filtered page set, run:
+```
+rg -l "<topic>" <pages in tool set>
+```
+Then grep section headers (`^##`) around matches to give context without full reads. Present results as a ranked list with the matching excerpt.
+
+### Diff Mode
+
+Compute:
+- `only_in_a` = `tool_pages[a]` − `tool_pages[b]`
+- `only_in_b` = `tool_pages[b]` − `tool_pages[a]`
+- `shared` = `tool_pages[a]` ∩ `tool_pages[b]`
+
+If no specific tools are given, compare all tools pairwise (limit to pairs with >0 overlap or unique pages to keep output concise).
+
+Present:
+
+```
+## Memory Bridge Diff — <tool-a> vs <tool-b>
+
+### Only in <tool-a> (<N> pages)
+These concepts exist in your wiki from <tool-a> sessions but <tool-b> has never touched them.
+<list with one-line descriptions from index.md>
+
+### Only in <tool-b> (<N> pages)
+<list>
+
+### Shared (<N> pages)
+Both tools have contributed to these pages.
+<list — only show if ≤15; otherwise just the count>
+
+### Notable gaps
+<highlight the most interesting asymmetries — e.g. "codex has 12 pages on build tooling that claude has never seen">
+```
+
+### Map Mode
+
+Build a matrix showing every page and which tools have touched it. Cap at 50 rows; sort by number of contributing tools descending (most cross-tool pages first — these are the richest nodes).
+
+```
+| Page | claude | codex | hermes | copilot | pi |
+|------|--------|-------|--------|---------|----|
+| [[react-patterns]] | ✓ | ✓ | — | ✓ | — |
+| [[rust-ownership]] | — | ✓ | — | — | ✓ |
+```
+
+## Step 3: Spawn impl-validator (if available)
+
+After generating output, if the `impl-validator` skill is available in the current environment, spawn it as a subagent:
+
+```
+impl-validator check:
+  goal: "Browse/diff wiki knowledge by source tool and surface cross-tool blind spots"
+  artifacts: [the output you just generated]
+  checks:
+    - Did you correctly parse source_type from .manifest.json?
+    - Are page counts plausible (not 0 unless vault is empty)?
+    - Is the diff symmetric (a−b and b−a are disjoint)?
+    - Did you avoid reading full page bodies when not needed?
+```
+
+Apply any issues it surfaces before presenting output to the user.
+
+## Step 4: Log
+
+Append to `$OBSIDIAN_VAULT_PATH/log.md`:
+```
+- [TIMESTAMP] MEMORY-BRIDGE mode=<browse|search|diff|map> tool=<tool> pages_shown=N
+```
+
+## Output Conventions
+
+- Always show page counts so the user can calibrate how much knowledge is in each tool's silo.
+- Use `[[wikilinks]]` for page references (or standard Markdown links if `OBSIDIAN_LINK_FORMAT=markdown` is set).
+- In diff mode, call out the most *surprising* asymmetry explicitly — that's the insight the user came for.
+- If `.manifest.json` is empty or missing, say so clearly and suggest running `/wiki-history-ingest` first.

package/bundled-skills/memory-save/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: memory-save
+description: >
+  Sauvegarder proprement un contenu dans le vault Obsidian de l'utilisateur en
+  choisissant TOUJOURS le bon dossier via la table de routage. Utilise cette skill
+  quand l'utilisateur demande "met à jour ma mémoire", "sauvegarde ceci/cela", "note
+  ça dans obsidian", "enregistre cette note", "mémorise", "save to memory", "add to
+  my obsidian", "où va cette note", ou veut classer un nouveau contenu (dev, formation,
+  trading) dans son vault. Garantit le respect de _meta/routing.md et _meta/taxonomy.md.
+---
+
+# memory-save — Sauvegarder dans le vault Obsidian
+
+Tu écris une page (ou quelques pages) dans le vault Obsidian de l'utilisateur à la **bonne place**.
+Tu ne devines jamais : tu suis la table de routage `_meta/routing.md`. En cas de doute, tu demandes.
+
+## Résolution du chemin du vault
+
+`OBSIDIAN_VAULT_PATH` : vault unique connu = `C:\Users\hiz\Documents\novahiz`.
+Si un autre chemin est fourni (`@nom`), vérifie qu'il existe avant tout.
+
+## Procédure obligatoire (dans l'ordre)
+
+### 1. Résoudre la config
+- Lire `_meta/routing.md` et `_meta/taxonomy.md` dans le vault (ils sont la source de vérité).
+- Vérifier que le vault et `_meta/routing.md` existent. Sinon : prévenir l'utilisateur, ne rien écrire.
+
+### 2. Classifier le contenu : domaine + type
+- **Domaine** : `dev` · `formation` · `trading` · `général` (hors domaine).
+- Pour `dev`, déduire la sous-stack à partir du contenu :
+  - React / Next / Vue / JS / browser → `web`
+  - Flutter / React Native / Swift / Kotlin / Android / iOS → `mobile`
+  - Electron / Tauri / .NET / WPF / SwiftUI / Qt → `desktop`
+  - Backend / API / infra générique → laisser au niveau global (`skills/` ou `references/`)
+- **Type de contenu** : raw source · note temporelle · how-to/skill · reference · concept ·
+  entity · synthesis · project · activité domaine (cours / TP / support / client · analyse /
+  stratégie / risque / économie).
+- Si l'un des deux axes est ambigu **ou** que deux dossiers sont plausibles : **demander à
+  l'utilisateur** (question à choix). Ne pas choisir au hasard.
+
+### 3. Afficher le chemin choisi AVANT d'écrire
+Toujours afficher, sous forme de bloc :
+
+```
+→ C:\Users\hiz\Documents\novahiz\<dossier>\<titre-si-pertinent>.md
+```
+
+Si l'utilisateur a demandé une sauvegarde directe et que le classement est évident (table sans
+ambiguïté), écrire immédiatement après l'affichage. Si le contenu touche à plusieurs domaines,
+proposer (a) de découper, (b) de choisir un dossier principal, (c) une page synthesis.
+
+### 4. Respecter les garde-fous
+- **Ne PAS écrire** dans : `index.md`, `log.md`, `hot.md`, `.manifest.json`, `.obsidian/`, `_meta/`. Ces fichiers sont **réservés aux skills de maintenance** (wiki-ingest, wiki-update, wiki-lint, wiki-status, cross-linker, graph-colorize) qui gèrent le journal et le graph. `memory-save` enregistre uniquement la page de contenu, jamais de traces ailleurs.
+- **Ne PAS créer de dossier racine**. Si la table ne couvre pas le sujet → demander ; si nécessaire,
+  créer l'entrée dans `routing.md` avec l'accord explicite de l'utilisateur.
+- Vérifier que le dossier cible existe. S'il manque, prévenir (ne pas recréer en silence).
+
+### 5. Écrire avec le format vault (frontmatter ar9av)
+Frontmatter obligatoire (YAML) :
+
+```yaml
+---
+title: <titre concis>
+category: <concept|entity|skill|reference|synthesis|journal|project|meta|raw>
+tags: [<domaine/...>, <type/...>, depuis _meta/taxonomy.md]
+sources: [<lien ou nom de la source d'origine si applicable>]
+created: <YYYY-MM-DD>
+updated: <YYYY-MM-DD>
+summary: <1–2 phrases>
+---
+```
+
+- `category` reflète le **type de page** (les mêmes catégories que `llm-wiki`) : `concept|entity|skill|reference|synthesis|journal|project|meta|raw`. Pas le domaine — le domaine vit dans `tags`.
+- `tags` : le **domaine** (`dev/...`, `formation/...`, `trading/...`) plus un `type/...` (cross-domaine) depuis `_meta/taxonomy.md`. Exemple : une note de stratégie forex → `tags: [trading/strategy, type/concept]`.
+- Corps de la note : contenu utile + `[[wikilinks]]` vers les pages liées existantes
+  (ou à créer). Si une page proche existe déjà, **fusionner ou lier** plutôt que dupliquer.
+- Ne pas donner de trace ailleurs qu'à l'étape 6.
+
+### 6. Rendre compte (court)
+Confirmer le dossier choisi + le fichier écrit + un rappel si une page existante a été mise à jour.
+
+## Cas particuliers
+
+- **Source brute** (article/PDF/page/export chat non encore traité) → `_raw/`. Ne pas distiller dans le corps ; la distillation est du ressort de `wiki-ingest`.
+- **Note temporelle / daily / session / trade daté** → `journal/`. Pour un trade forex précis, entrée dans `journal/` datée (tags `trading/forex`, `trading/analyse`) et le détail d'analyse complet dans `areas/trading/analyse` si volumineux.
+- **Projet / repo de code** → `projects/<nom>.md` (ou via `wiki-update`).
+- **« Où va cette note ? »** → répondre avec la ligne de la table concernée, sans écrire.
+- **Contraire (annuler une sauvegarde erronée)** → indiquer le fichier écrit et le déplacer avec accord.

package/bundled-skills/migrate/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: "migrate"
+description: >-
+  Migrate from Cypress or Selenium to Playwright. Use when user mentions
+  "cypress", "selenium", "migrate tests", "convert tests", "switch to
+  playwright", "move from cypress", or "replace selenium".
+---
+
+# Migrate to Playwright
+
+Interactive migration from Cypress or Selenium to Playwright with file-by-file conversion.
+
+## Input
+
+`$ARGUMENTS` can be:
+- `"from cypress"` — migrate Cypress test suite
+- `"from selenium"` — migrate Selenium/WebDriver tests
+- A file path: convert a specific test file
+- Empty: auto-detect source framework
+
+## Steps
+
+### 1. Detect Source Framework
+
+Use `Explore` subagent to scan:
+- `cypress/` directory or `cypress.config.ts` → Cypress
+- `selenium`, `webdriver` in `package.json` deps → Selenium
+- `.py` test files with `selenium` imports → Selenium (Python)
+
+### 2. Assess Migration Scope
+
+Count files and categorize:
+
+```
+Migration Assessment:
+- Total test files: X
+- Cypress custom commands: Y
+- Cypress fixtures: Z
+- Estimated effort: [small|medium|large]
+```
+
+| Size | Files | Approach |
+|---|---|---|
+| Small (1-10) | Convert sequentially | Direct conversion |
+| Medium (11-30) | Batch in groups of 5 | Use sub-agents |
+| Large (31+) | Use `/batch` | Parallel conversion with `/batch` |
+
+### 3. Set Up Playwright (If Not Present)
+
+Run `/pw:init` first if Playwright isn't configured.
+
+### 4. Convert Files
+
+For each file, apply the appropriate mapping:
+
+#### Cypress → Playwright
+
+Load `cypress-mapping.md` for complete reference.
+
+Key translations:
+```
+cy.visit(url)           → page.goto(url)
+cy.get(selector)        → page.locator(selector) or page.getByRole(...)
+cy.contains(text)       → page.getByText(text)
+cy.find(selector)       → locator.locator(selector)
+cy.click()              → locator.click()
+cy.type(text)           → locator.fill(text)
+cy.should('be.visible') → expect(locator).toBeVisible()
+cy.should('have.text')  → expect(locator).toHaveText(text)
+cy.intercept()          → page.route()
+cy.wait('@alias')       → page.waitForResponse()
+cy.fixture()            → JSON import or test data file
+```
+
+**Cypress custom commands** → Playwright fixtures or helper functions
+**Cypress plugins** → Playwright config or fixtures
+**`before`/`beforeEach`** → `test.beforeAll()` / `test.beforeEach()`
+
+#### Selenium → Playwright
+
+Load `selenium-mapping.md` for complete reference.
+
+Key translations:
+```
+driver.get(url)                    → page.goto(url)
+driver.findElement(By.id('x'))     → page.locator('#x') or page.getByTestId('x')
+driver.findElement(By.css('.x'))   → page.locator('.x') or page.getByRole(...)
+element.click()                    → locator.click()
+element.sendKeys(text)             → locator.fill(text)
+element.getText()                  → locator.textContent()
+WebDriverWait + ExpectedConditions → expect(locator).toBeVisible()
+driver.switchTo().frame()          → page.frameLocator()
+Actions                            → locator.hover(), locator.dragTo()
+```
+
+### 5. Upgrade Locators
+
+During conversion, upgrade selectors to Playwright best practices:
+- `#id` → `getByTestId()` or `getByRole()`
+- `.class` → `getByRole()` or `getByText()`
+- `[data-testid]` → `getByTestId()`
+- XPath → role-based locators
+
+### 6. Convert Custom Commands / Utilities
+
+- Cypress custom commands → Playwright custom fixtures via `test.extend()`
+- Selenium page objects → Playwright page objects (keep structure, update API)
+- Shared helpers → TypeScript utility functions
+
+### 7. Verify Each Converted File
+
+After converting each file:
+
+```bash
+npx playwright test <converted-file> --reporter=list
+```
+
+Fix any compilation or runtime errors before moving to the next file.
+
+### 8. Clean Up
+
+After all files are converted:
+- Remove Cypress/Selenium dependencies from `package.json`
+- Remove old config files (`cypress.config.ts`, etc.)
+- Update CI workflow to use Playwright
+- Update README with new test commands
+
+Ask user before deleting anything.
+
+## Output
+
+- Conversion summary: files converted, total tests migrated
+- Any tests that couldn't be auto-converted (manual intervention needed)
+- Updated CI config
+- Before/after comparison of test run results