feat: add PageTrail Inspector

.agents/rules/agents.md

@@ -0,0 +1,23 @@
+# Agent Guidance Rules
+
+Use these rules when creating or updating project agent guidance.
+
+## Skills
+
+- Store project skills in `.agents/skills/<skill-name>/SKILL.md`.
+- Use lowercase hyphen-case skill names.
+- Keep skills short and consistent with the existing files in `.agents/skills`.
+- Include only `name` and `description` in YAML frontmatter.
+- Make `description` specific enough to trigger the skill in the right tasks.
+- In the body, list required context and a short workflow.
+- Reference `.agents/rules/*` instead of duplicating rule text in skills.
+- Do not add `agents/openai.yaml`, scripts, references, assets, or extra docs
+  unless the user explicitly asks or the skill cannot work without them.
+- Add every new project skill to `AGENTS.md`.
+
+## Rules
+
+- Store project rules in `.agents/rules/<topic>.md`.
+- Keep rules concise, task-focused, and reusable by multiple skills.
+- Add every new project rule to `AGENTS.md`.
+- Prefer updating an existing rule over creating overlapping guidance.

.agents/rules/architecture.md

@@ -0,0 +1,10 @@
+# Architecture Rules
+
+Architecture source of truth:
+
+- `docs/ARCHITECTURE.md`
+- `docs/DOM-TO-RAG-PIPELINE.md`
+
+Read these docs before architectural or DOM-to-RAG pipeline changes.
+
+If docs conflict with code, treat code as primary and update docs.

.agents/rules/changelog.md

@@ -0,0 +1,32 @@
+# Changelog Rules
+
+Use these rules when creating, updating, or reviewing `CHANGELOG.md`.
+
+## Goal
+
+Keep `CHANGELOG.md` as a concise record of notable project changes.
+
+## Source of truth
+
+Use the current repository diff and existing `CHANGELOG.md` format as the source
+of truth. Do not add entries for work that is not present in the codebase.
+
+## Format
+
+- Keep the top-level title as `# Changelog`.
+- Keep the introductory sentence below the title.
+- Put unreleased branch changes under `## [Unreleased]`.
+- Group released changes by version using `## [x.y.z] - YYYY-MM-DD`.
+- Keep `## [Unreleased]` above released versions; keep released versions in reverse chronological order.
+- Group entries under `### Added`, `### Changed`, `### Fixed`, `### Removed`, or another Keep a Changelog-style category only when it is needed.
+- Write entries as Markdown bullet points.
+- Keep each entry short, user-visible, and specific.
+- Use links only when they add useful context, such as a public demo URL.
+
+## Rules
+
+- Record notable user-visible, behavior, documentation, packaging, or architecture changes.
+- Do not include low-level implementation noise unless it changes behavior, public contracts, or project usage.
+- Do not duplicate the backlog, commit history, or pull request description.
+- Do not invent release dates or versions. If `## [Unreleased]` is absent, create it above the latest released version and add branch changes there.
+- Preserve existing wording and categories unless the current change requires a precise update.

.agents/rules/code-style.md

@@ -0,0 +1,39 @@
+# Code Style and Engineering Practices
+
+Use these rules when writing or reviewing code in this repository.
+
+## General
+
+- Keep modules small, explicit, and easy to reason about.
+- Prefer clear domain names over generic abstractions.
+- Keep one source of truth for state; avoid mirrored state unless it is intentionally derived and synchronized.
+- Handle async failures at the boundary where the user or caller can act on them.
+- Treat external input, selectors, page data, model output, and browser APIs as unreliable.
+- Prefer typed contracts over loosely shaped objects.
+- Avoid adding dependencies unless they materially reduce project complexity.
+- Keep generated UI text and diagnostics concise and actionable.
+
+## `packages/page-trail`
+
+- Maintain strong test coverage for every behavior change.
+- Cover collectors, extractors, importance scoring, semantic formatting, markdown generation, and utility edge cases.
+- Use DOM fixtures for behavior that depends on real document structure.
+- Test privacy and safety behavior, especially sensitive value filtering.
+- Keep extraction deterministic; avoid hidden global state.
+- Preserve stable output shapes because backend indexing and extension navigation depend on them.
+
+## `apps/extension`
+
+- Keep the extension lightweight: minimize runtime dependencies, bundle size, DOM work, and long-lived listeners.
+- Keep UI components mostly presentational; place messaging, storage, and page effects in hooks or services.
+- Avoid duplicated component state. Parent view models should own workflow state such as wizard progress.
+- Guard async UI actions against duplicate submits, races, and unavailable content scripts.
+- Keep accessibility claims truthful: do not mark UI as modal without modal behavior, and keep tabs, dialogs, buttons, and panels keyboard-accessible.
+- Preserve page isolation through Shadow DOM, scoped class names, prefixed attributes, and minimal global CSS impact.
+- Prefix extension-owned CSS classes, custom properties, data attributes, and DOM IDs with `flowforge`, not abbreviations like `ff`.
+- Be careful with host-page selectors and DOM mutation. Escape selector values and fail safely when target elements disappear.
+- Prefer Preact-compatible patterns that avoid unnecessary re-renders and expensive layout work.
+
+## `apps/backend`
+
+Reserved for backend-specific rules.

.agents/rules/documentation.md

@@ -0,0 +1,126 @@
+# Documentation Rules
+
+Use these rules when creating or updating project documentation.
+
+## Goal
+
+Update documentation based strictly on the current codebase and existing docs.
+
+Rewrite and align documentation. Do not invent or expand it beyond the
+implemented project.
+
+## Sources of truth
+
+1. Codebase
+2. Existing documentation
+
+If something is unclear or missing, omit it.
+
+## Files to update
+
+- `README.md`
+- `docs/ARCHITECTURE.md`
+- `docs/DOM-TO-RAG-PIPELINE.md`
+- `packages/page-trail/README.md`
+- `apps/backend/README.md`
+- `apps/extension/README.md`
+
+## Rules
+
+- Do not invent features, APIs, workflows, or architecture.
+- Keep terminology consistent across all docs.
+- Align all documents with each other and the codebase.
+- Avoid duplication between files.
+- Be concise, clear, and structured.
+- Keep links valid.
+- Keep commands correct.
+- Keep Markdown clean.
+- If content exceeds scope, trim it instead of expanding other docs.
+
+## Document roles
+
+- `README.md` — entry point: what it is and how to run it.
+- `docs/ARCHITECTURE.md` — high-level system overview.
+- `docs/DOM-TO-RAG-PIPELINE.md` — DOM-to-RAG pipeline description.
+- `packages/page-trail/README.md` — canonical DOM representation (`PageTrail`).
+- `apps/backend/README.md` — backend responsibilities and usage.
+- `apps/extension/README.md` — extension responsibilities and usage.
+
+## Target structure
+
+### `README.md`
+
+Target length: 100–120 lines.
+
+- "Forging your experience..."
+- Demo
+- Overview
+- Use cases
+- Disclaimer
+- Quick start
+- Usage
+- Security
+- Roadmap
+- Documentation
+- License
+
+### `docs/ARCHITECTURE.md`
+
+Target length: 80–100 lines.
+
+- Overview
+- Components
+- Interaction flow
+- Pipeline (high-level)
+- Key decisions
+- Contracts
+- Constraints
+
+### `docs/DOM-TO-RAG-PIPELINE.md`
+
+Target length: 80–100 lines.
+
+- Link to `packages/page-trail/README.md` for more information about the canonical DOM snapshot format.
+- Overview
+- Stages:
+    - Extraction to structure representation
+    - Transforming to semantic representation
+    - Indexing / retrieval
+    - Reranking
+    - Resolution to tool results
+
+### `packages/page-trail/README.md`
+
+Target length: 60–80 lines.
+
+- Overview
+- Structure
+- Content elements
+- Interactive elements
+- Context
+- Importance
+- Format
+- Usage
+
+### `apps/backend/README.md`
+
+Target length: 50–60 lines.
+
+- Purpose
+- Responsibilities
+- Run
+- Configuration
+- API (short)
+- Key parts
+- Notes
+
+### `apps/extension/README.md`
+
+Target length: 50–60 lines.
+
+- Purpose
+- Responsibilities
+- Run
+- Load in Chrome
+- Key parts
+- Notes

.agents/skills/code-review/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: code-review
+description: Review FlowForge branch changes against master/main, architecture rules, code-style rules, changelog rules, CHANGELOG.md, and docs/BACKLOG.md.
+---
+
+# Code Review
+
+Use this skill when reviewing branch changes.
+
+## Required context
+
+- `.agents/rules/architecture.md`
+- `.agents/rules/code-style.md`
+- `.agents/rules/changelog.md`
+- `CHANGELOG.md`
+- `docs/BACKLOG.md`
+
+## Workflow
+
+1. Compare the branch with `master`; use `main` only if `master` is absent.
+2. Inspect `git status --short` and the diff from the merge base.
+3. Review architecture and code style using the required context.
+4. For `packages/page-trail`, check that behavior changes are well covered by tests.
+5. For `apps/extension`, check lightweight implementation, component state ownership, async handling, a11y truthfulness, page isolation, and selector safety.
+6. Verify behavior or user-visible changes are reflected in `CHANGELOG.md` according to `.agents/rules/changelog.md`.
+7. Verify completed work is reflected in `docs/BACKLOG.md`: if a backlog item was implemented, it should be removed from the backlog.
+8. Report findings by severity with file, problem, impact, and suggested fix.

.agents/skills/update-changelog/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: update-changelog
+description: Update FlowForge CHANGELOG.md from changes since the latest release tag using changelog rules.
+---
+
+# Update Changelog
+
+Use this skill when updating `CHANGELOG.md` from changes since the latest release tag.
+
+## Required context
+
+- `.agents/rules/changelog.md`
+- `CHANGELOG.md`
+
+## Workflow
+
+1. Find the latest release tag using version tags such as `vX.Y.Z`; do not use `master` or `main` as the comparison baseline.
+2. Inspect `git status --short` and the diff from the latest release tag.
+3. Read `.agents/rules/changelog.md` and follow it strictly.
+4. Inspect existing `CHANGELOG.md` format and target section.
+5. Add only notable changes present in the branch diff.
+6. Do not add low-level implementation noise, duplicate existing entries, or invent versions/dates.
+7. If the target release section is unclear, ask before editing.
+8. Report the section changed and a short summary of entries added or omitted.

.agents/skills/update-docs/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: update-docs
+description: Update project documentation based strictly on the current codebase and existing docs.
+---
+
+# Update Docs
+
+Use this skill when updating project documentation.
+
+## Required context
+
+- `.agents/rules/documentation.md`
+- `.agents/rules/architecture.md`
+
+## Workflow
+
+1. Review the documentation targets.
+2. Inspect the relevant code before changing docs.
+3. Identify stale, duplicated, or unsupported claims.
+4. Update docs according to the documentation rules.
+5. Run relevant formatting or validation checks if available.