jourilo 1.0.1 → 1.1.0

package/README.md

@@ -1,37 +1,86 @@
-<h1>
+<p align="center">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/brand/jourilo-wordmark-reversed.svg">
-    <img src="docs/assets/brand/jourilo-wordmark.svg" alt="Jourilo" width="240">
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/cihantopac/jourilo/v1.1.0/docs/assets/brand/jourilo-wordmark-reversed.svg">
+    <img src="https://raw.githubusercontent.com/cihantopac/jourilo/v1.1.0/docs/assets/brand/jourilo-wordmark.svg" alt="Jourilo" width="260">
   </picture>
-</h1>
+</p>
 
-**AI-powered product experience & conversion engineering studio.** Jourilo drives a real browser through your
-product, finds UX, accessibility, performance and conversion problems with evidence, traces them to the code that
-causes them, applies safe fixes and proves the result with a before/after run.
+<h3 align="center">Walk every journey. Find the friction. Prove the fix.</h3>
 
-Local-first · evidence-driven · no paid services required · works as a CLI and as a Claude Code plugin · Apache-2.0
+<p align="center">
+  Jourilo uses your product in a real browser, shows where people get stuck with screenshot evidence,<br>
+  traces each problem to its root cause and proves every fix with a before/after run.<br>
+  A CLI and a Claude Code plugin. Local-first, open source.
+</p>
 
-![Jourilo report overview: defects by severity, conversion hypotheses kept separate, fixes grouped by root cause](docs/assets/report-overview.png)
+<p align="center">
+  <a href="https://www.npmjs.com/package/jourilo"><img alt="npm" src="https://img.shields.io/npm/v/jourilo?color=875802&label=npm"></a>
+  <a href="https://github.com/cihantopac/jourilo/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/cihantopac/jourilo/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="LICENSE"><img alt="License: Apache-2.0" src="https://img.shields.io/badge/license-Apache--2.0-1c1a17"></a>
+  <img alt="Node.js ≥ 20.10" src="https://img.shields.io/badge/node-%E2%89%A5%2020.10-1c1a17">
+</p>
 
-> Status: **1.0.1.** Tested in CI on Linux, macOS and Windows (Node 20 and 22) with Chromium, Firefox and WebKit. An
-> automated run never proves WCAG conformance: see [Limitations](docs/LIMITATIONS.md) for what is not covered.
+<p align="center">
+  <a href="#install">Install</a> ·
+  <a href="#in-claude-code">Claude Code</a> ·
+  <a href="#audit--understand--fix--verify">How it works</a> ·
+  <a href="#benchmarks">Benchmarks</a> ·
+  <a href="docs/WORKFLOW.md">Guide</a> ·
+  <a href="docs/">Docs</a>
+</p>
 
-## What it does
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/cihantopac/jourilo/v1.1.0/docs/assets/report-overview-dark.png">
+  <img src="https://raw.githubusercontent.com/cihantopac/jourilo/v1.1.0/docs/assets/report-overview.png" alt="The Jourilo report: verified defects, root causes, automatic fixes, manual review and conversion hypotheses as separate counts, then the highest-impact root causes with their screenshots">
+</picture>
 
-|                             |                                                                                                                                                                                                                                                                                                                                                     |
-| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Understand**              | `discover` maps a repository (Next.js, Nuxt, SvelteKit, Astro, Remix, React/Vue Router, Laravel, Flutter web, static sites, monorepos) or a live site: routes, dev command, design system, i18n, auth, payments, analytics, roles and candidate journeys. Every fact names the file or page it came from.                                           |
-| **Audit in a real browser** | Playwright + axe-core 4.14 (WCAG 2.0–2.2 A/AA), a keyboard-only walk (focus visible, focus obscured, traps), target size, reflow at 320 px, horizontal overflow, input purpose, paste blocking, form error feedback, lab Web Vitals (LCP, CLS, FCP, TTFB, TBT; INP during journeys), JavaScript errors and failed requests — on desktop and mobile. |
-| **Journeys**                | Reusable JSON scenarios with explicit success criteria, suggested from what the site actually contains, run with a screenshot per step. A safety policy never pays, deletes or cancels on non-local hosts.                                                                                                                                          |
-| **Conversion**              | CTA prominence and clarity, value proposition, trust signals, signup/checkout friction, pricing clarity — always reported as **hypotheses**, never as predicted lifts, with experiment plans and the statistics to read real results.                                                                                                               |
-| **Fix and verify**          | Findings point to likely source lines. `optimize` previews minimal fixes as diffs and applies them only with `--apply`, as one reversible change (atomic writes; rollback never overwrites later edits). `verify` repeats the exact scope and reports fixed, new and persisting problems.                                                           |
-| **Report**                  | A self-contained HTML _Experience Observatory_ (screenshots with highlighted elements, reproduction steps, standards, sources, journeys, before/after), plus Markdown for PRs and SARIF for code scanning.                                                                                                                                          |
+## It walks the journey, step by step
 
-What Jourilo does **not** do: invent observations, give a single "UX score", claim WCAG compliance from an automated
-run, or predict conversion gains. Each finding is labelled _measured_, _observed_, _heuristic_, _AI inference_ or
-_user input_.
+Jourilo signs up, checks out and follows calls to action like a person would, with a real screenshot of every step.
+When a journey breaks, you see exactly where.
 
-## Quick start
+<img src="https://raw.githubusercontent.com/cihantopac/jourilo/v1.1.0/docs/assets/report-journeys.png" alt="A sign-up journey on mobile: the form is filled in, Submit is clicked, the page resets, and the goal 'leaves the form page' is not met">
+
+## Evidence you can see
+
+Every finding comes with the element outlined on its screenshot, the measured values, the WCAG criterion, reproduction
+steps and the likely source line. Findings with one cause are grouped into one fix. Verified defects, items that need a
+person and conversion hypotheses are always kept apart, and there is no made-up overall score.
+
+<img src="https://raw.githubusercontent.com/cihantopac/jourilo/v1.1.0/docs/assets/report-finding.png" alt="A finding: the page scrolls sideways at 390 px, with the measured widths, WCAG 1.4.10, the CSS rule that causes it and the element highlighted on the mobile screenshot">
+
+## Audit → Understand → Fix → Verify
+
+<img src="https://raw.githubusercontent.com/cihantopac/jourilo/v1.1.0/docs/assets/workflow.png" alt="Four steps: audit in a real browser, understand by root cause, fix with approved patches or a repair prompt, verify with a before/after run">
+
+## Fix it yourself, automatically or with your agent
+
+- **Automatic fixes** for mechanical defects (missing `lang`, viewport, autocomplete, focus styles, paste blocking,
+  image sizes, placeholder labels): `jourilo optimize` previews minimal diffs and writes them only with `--apply`, as
+  one reversible change.
+- **Repair prompts** for everything else: select findings or root causes in the report and copy or download an
+  editable Markdown prompt for Claude Code or any coding agent. It carries ids, pages, screenshots, likely source files
+  and reproduction steps, and asks the agent to revalidate, change as little as possible, add regression tests and
+  verify with Jourilo.
+- **Experiment briefs** for conversion hypotheses, never code changes or promised lifts.
+
+<img src="https://raw.githubusercontent.com/cihantopac/jourilo/v1.1.0/docs/assets/report-prompt.png" alt="The repair prompt dialog: an editable Markdown brief with copy and download buttons, generated from three selected findings">
+
+## Prove it
+
+`jourilo verify` repeats the same pages, viewports and journeys and shows what is fixed, new or still present, with the
+same region of the page before and after.
+
+<img src="https://raw.githubusercontent.com/cihantopac/jourilo/v1.1.0/docs/assets/report-before-after.png" alt="Before / after: 14 fixed, 0 new, 18 still present, with before and after crops of each fixed problem">
+
+## One file, any screen, two languages
+
+The report is a single offline HTML file. It follows the browser's language and theme, and you can switch between
+English and Turkish and between light, dark and system appearance.
+
+<img src="https://raw.githubusercontent.com/cihantopac/jourilo/v1.1.0/docs/assets/report-mobile.png" alt="The report on two phones: English in the light theme and Turkish in the dark theme">
+
+## Install
 
 Requires Node.js ≥ 20.10.
 
@@ -43,122 +92,64 @@ npm install -g jourilo
 jourilo setup
 ```
 
-`setup` downloads Playwright's Chromium (one time, ~150 MB). Alternatively use an installed Chrome with
-`--browser chrome`. To run without a global install, use `npx jourilo <command>`; from a clone of this repository,
-`node plugin/dist/jourilo.mjs <command>`.
-
-Audit a local static build (served on 127.0.0.1) and map findings to its source:
-
 ```bash
-jourilo audit ./dist --repo .
+jourilo audit http://localhost:3000 --repo .
 ```
 
-Audit a running app or a website (read-only, respects robots.txt):
+`setup` downloads Playwright's Chromium once. The report is written to `.jourilo/runs/<run-id>/report.html`.
+More commands and the full loop: [docs/WORKFLOW.md](docs/WORKFLOW.md) and the [CLI reference](docs/CLI.md).
 
-```bash
-jourilo audit http://localhost:3000 --viewports desktop,mobile,reflow
-```
-
-The report is written to `.jourilo/runs/<run-id>/report.html` (git-ignored). Add `--json` to any command for
-machine-readable output.
-
-### Claude Code plugin
+## In Claude Code
 
 ```text
 /plugin marketplace add cihantopac/jourilo
 /plugin install jourilo@jourilo
 ```
 
-Then use `/jourilo:jourilo <url or path>` for the full workflow, or `/jourilo:discover`, `/jourilo:audit`,
-`/jourilo:journeys`, `/jourilo:accessibility`, `/jourilo:conversion`, `/jourilo:optimize`, `/jourilo:compare`,
-`/jourilo:report`, `/jourilo:experiment`. Plugin commands are namespaced; `/jourilo:jourilo` always works. Claude
-Code may also accept a bare `/jourilo` when no other command uses that name; to make it permanent, install the
-personal skill with `jourilo agent install claude-skill --write`. See [docs/PLUGIN.md](docs/PLUGIN.md).
-
-Other agents: `jourilo agent install codex --write` (adds a section to `AGENTS.md`) or `cursor`
-(`.cursor/rules/jourilo.mdc`).
-
-## The improvement loop
-
-```bash
-jourilo audit http://localhost:3000 --repo .        # evidence + likely source lines
-jourilo journeys suggest latest                     # edit .jourilo/journeys/*.json
-jourilo journeys run --base http://localhost:3000   # step screenshots, success criteria
-jourilo optimize latest --repo .                    # preview minimal diffs (dry run)
-jourilo optimize latest --repo . --apply            # write as one reversible change
-jourilo verify <baseline-run>                       # same scope again: fixed / new / persisting
-jourilo rollback latest --yes                       # undo if needed
-```
-
-Measured on the seeded demo app (`fixtures/sites/acme-saas`): `verify` after `optimize --apply` reported 11 findings
-fixed and 0 new; on a page with a late-loading image, adding the measured image size took mobile CLS from 0.121 to 0.
-Fixes are idempotent and fully reversible (see [docs/EVALUATION.md](docs/EVALUATION.md)).
-
-| Finding with evidence and root cause                                                                                                             | Journey storyboard                                                                                                 |
-| ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
-| ![A finding with standard, reproduction steps, likely source line and the element highlighted on the screenshot](docs/assets/report-finding.png) | ![Journeys with a screenshot per step, success criteria and the step that failed](docs/assets/report-journeys.png) |
-
-## Detection quality
+Then `/jourilo:jourilo https://your-site.dev` or `/jourilo:jourilo .` for a repository. Claude answers in a few lines
+(blocked journeys, three priorities, the fixes available, the report path and one next step) and keeps the evidence in
+the report. All commands: [docs/PLUGIN.md](docs/PLUGIN.md).
 
-**Fixture benchmark** (`jourilo bench`, a CI gate): sites with seeded problems and clean control pages; it fails on
-any miss, false positive or wrong root-cause file. 1.0.0: **45 / 45** seeded problems found, **0** false positives,
-root cause in the expected file 9 / 9 (Chromium; the `acme-saas` set also in Firefox and WebKit). These fixtures were written alongside the
-rules, so they show the rules work as designed.
+## Benchmarks
 
-**Independent benchmark** on the 955 [W3C ACT Rules](https://www.w3.org/WAI/standards-guidelines/act/rules/) test
-cases that map to WCAG criteria, written by the ACT Rules Community Group, not for Jourilo:
+On the 955 [W3C ACT Rules](https://www.w3.org/WAI/standards-guidelines/act/rules/) test cases that map to WCAG criteria,
+written by the ACT Rules Community Group and not for Jourilo (measured 2026-11-01; the detection engine is unchanged
+in 1.1.0):
 
-| 2026-11-01            | Precision | Recall | False positives |
+|                       | Precision | Recall | False positives |
 | --------------------- | --------- | ------ | --------------- |
 | Jourilo 1.0.0         | 93.9 %    | 55.4 % | 11              |
 | axe-core 4.14.0 alone | 93.6 %    | 53.5 % | 11              |
 
-Jourilo runs axe-core internally; its own checks add keyboard-trap and focus-indicator detections without adding
-false positives. Many misses are criteria that need a person (media alternatives, meaning, descriptive headings), which
-every report lists under "Still needs a person". A separate comparison with Pa11y and Lighthouse on the 142 cases of the
-[GOV.UK accessibility tool audit](https://alphagov.github.io/accessibility-tool-audit/) is in
-[docs/EVALUATION.md](docs/EVALUATION.md#comparison), with its method and caveats.
-
-## Safety and privacy
-
-Audits are read-only, on every host: form validation is probed by simulating the submission, and nothing that would
-change data leaves the browser unless you pass `--allow-submit`. Crawling stays on the target origin and respects
-robots.txt. Every browser request goes through a local network guard, so an audited page cannot reach this machine,
-the local network or cloud-metadata services (private targets need `--allow-private`). Journeys block payments,
-purchases, deletions and cancellations however they are triggered (click, key, script, link) on any non-local host,
-and on local hosts unless you pass `--allow-destructive`. Fixes are written as one reversible change, and rollback
-never overwrites edits made afterwards. Password, card and marked fields are masked
-in screenshots; tokens, keys, e-mail addresses and card numbers are redacted from logs and reports. Page content is
-treated as untrusted data and is always HTML-escaped in reports. Details: [docs/PRIVACY.md](docs/PRIVACY.md),
-[docs/SECURITY-REVIEW.md](docs/SECURITY-REVIEW.md) (including residual risks), [SECURITY.md](SECURITY.md).
-
-## Works with Markilo and Searvex (optional)
-
-If a project contains [Markilo](https://github.com/cihantopac/markilo) brand tokens, Jourilo checks buttons and fonts
-against the brand and never recommends changing a locked brand color. If it contains
-[Searvex](https://github.com/cihantopac/searvex) results, search findings for the same pages appear in the report.
-Both are read through a small, versioned, tool-neutral contract, `jourilo.context/v1`
-([docs/INTEGRATIONS.md](docs/INTEGRATIONS.md)). Neither is required.
+Jourilo runs axe-core and adds its own keyboard-trap and focus-indicator checks. Many misses are criteria only a person
+can judge, which every report lists. No automated run shows WCAG conformance. Method, fixture benchmark and a
+comparison with Pa11y and Lighthouse: [docs/EVALUATION.md](docs/EVALUATION.md).
 
-## Documentation
+## Safe by default
+
+Audits are read-only, respect robots.txt and run behind a network guard that keeps audited pages away from your
+machine and network. Journeys never pay, delete or cancel on non-local hosts. Secrets are masked in screenshots and
+redacted from reports. Details: [docs/PRIVACY.md](docs/PRIVACY.md) · [SECURITY.md](SECURITY.md).
 
-- [CLI reference](docs/CLI.md) (generated from the code)
-- [Architecture](docs/ARCHITECTURE.md) · [Decisions](docs/DECISIONS.md) · [Requirements and quality targets](docs/REQUIREMENTS.md)
-- [Journeys format](docs/JOURNEYS.md) · [Claude Code plugin and agents](docs/PLUGIN.md) · [Integrations](docs/INTEGRATIONS.md)
-- [Evaluation](docs/EVALUATION.md) · [Limitations](docs/LIMITATIONS.md) · [Roadmap](docs/ROADMAP.md) · [Progress log](docs/PROGRESS.md)
-- Research: [tool landscape](docs/research/landscape.md) · [standards reference](docs/research/standards.md)
+## The family
 
-## Contributing
+Jourilo works on its own and pairs with its siblings through a small, optional contract
+([docs/INTEGRATIONS.md](docs/INTEGRATIONS.md)):
 
-Bug reports, fixture sites with real-world UX problems and new rules are welcome. Start with
-[CONTRIBUTING.md](CONTRIBUTING.md). Every rule needs a fixture that proves it fires and a control that proves it does
-not.
+- [**Relivaro**](https://github.com/cihantopac/relivaro) — code quality, security and release readiness.
+- [**Searvex**](https://github.com/cihantopac/searvex) — SEO and AI-search findings; Jourilo shows them for the same pages.
+- [**Markilo**](https://github.com/cihantopac/markilo) — brand identity; Jourilo checks against its tokens and never
+  changes a locked brand. Jourilo's own logo was made with Markilo.
+
+## Documentation
 
-## Brand
+[Guide](docs/WORKFLOW.md) · [CLI](docs/CLI.md) · [Plugin](docs/PLUGIN.md) · [Journeys](docs/JOURNEYS.md) ·
+[Evaluation](docs/EVALUATION.md) · [Limitations](docs/LIMITATIONS.md) · [Architecture](docs/ARCHITECTURE.md) ·
+[Decisions](docs/DECISIONS.md) · [Roadmap](docs/ROADMAP.md) · [Changelog](CHANGELOG.md)
 
-The Jourilo logo, symbol and plugin icon (the SVGs in [docs/assets/brand](docs/assets/brand)) were designed with
-[Markilo](https://github.com/cihantopac/markilo), a brand identity studio for Claude Code.
+Contributions are welcome: see [CONTRIBUTING.md](CONTRIBUTING.md). Every rule needs a fixture that proves it fires and a
+control that proves it does not.
 
 ## License
 
-[Apache-2.0](LICENSE). Bundled third-party code: see [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
+[Apache-2.0](LICENSE). Bundled third-party code: [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jourilo",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "AI-powered product experience & conversion engineering studio: real-browser journeys, UX, accessibility, performance and conversion audits with evidence, root causes and verified fixes.",
   "license": "Apache-2.0",
   "type": "module",

package/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "jourilo",
   "displayName": "Jourilo",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "AI-powered product experience & conversion engineering studio: discovers products and user journeys, operates real interfaces in Playwright, detects UX, accessibility (WCAG 2.2), performance and conversion problems with evidence, locates root causes, applies safe fixes and verifies them.",
   "author": {
     "name": "Cihan Topaç",