fsq-agent 0.1.0__tar.gz

fsq_agent-0.1.0/.gitignore

@@ -0,0 +1,39 @@
+.venv/
+uv.lock
+.DS_Store
+**/.DS_Store
+.vscode/*
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.env
+config.local.yaml
+cases/
+.fsq-agent-workspace/
+logs/
+log/
+output/
+reports/
+screenshots/
+dist/
+*.egg-info/
+knowledge/*
+!knowledge/skills/
+!knowledge/skills/**
+node_modules/
+.frontend-dist/
+fsq_agent/adapters/control_plane/playground/static/
+fsq_agent/adapters/control_plane/static/
+fsq_agent/resources/
+
+
+# Private/local planning material. Do not commit.
+docs/fsq-opensource-strategy.md
+docs/fsq-benchmark-metrics.md
+docs/README-draft.md
+docs/superpowers/
+private/
+docs/private/
+*.internal.md
+*.private.md

fsq_agent-0.1.0/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes are documented here. FSQ follows Semantic Versioning after publication; during the 0.x alpha period, minor releases may change public behavior with release-note guidance.
+
+## [Unreleased]
+
+### Added
+
+- Initial open-source release preparation.
+
+### Removed
+
+- Removed the legacy Playground browser application, standalone HTTP server, Python APIs, and packaged frontend assets. Use `fsq ui` for the supported Control Plane browser workflows; raw YAML dynamic execution, lifecycle-hook editing, completed-Run loading, and automatic Goal Case publication are not carried forward.
+
+## [0.1.0] - Unreleased
+
+### Added
+
+- Evidence-first AI exploration and deterministic Case replay across Web, Android, Windows, and macOS.
+- Local Workspace configuration, readiness diagnostics, user-level Provider configuration, Run queries, redacted logs, and offline HTML reports.
+- Local Control Plane for Workspace, Provider, Case, Run, and evidence workflows.
+- GitHub Copilot and Azure OpenAI Provider configuration.
+- Wheel and source distributions containing all supported Python platform dependencies and compiled frontend assets.
+
+### Stability
+
+- This is an alpha release. Public APIs and Case authoring details may evolve before 1.0.
+
+[Unreleased]: https://github.com/microsoft/FSQ/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/microsoft/FSQ/releases/tag/v0.1.0

fsq_agent-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Microsoft
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fsq_agent-0.1.0/PKG-INFO

@@ -0,0 +1,272 @@
+Metadata-Version: 2.5
+Name: fsq-agent
+Version: 0.1.0
+Summary: Goal-driven FSQ automated testing agent built around OpenAI Agents SDK, Azure OpenAI, harness actions, local utilities, observation, and reporting.
+Project-URL: Documentation, https://github.com/microsoft/FSQ#readme
+Project-URL: Issues, https://github.com/microsoft/FSQ/issues
+Project-URL: Repository, https://github.com/microsoft/FSQ
+Author: Microsoft Corporation
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.11
+Requires-Dist: aiofiles==25.1.0
+Requires-Dist: appium-python-client==5.3.1
+Requires-Dist: click==8.3.3
+Requires-Dist: jinja2==3.1.6
+Requires-Dist: openai-agents==0.15.2
+Requires-Dist: openai==2.34.0
+Requires-Dist: pillow==12.3.0
+Requires-Dist: playwright==1.60.0
+Requires-Dist: pydantic-settings==2.14.2
+Requires-Dist: pydantic==2.13.3
+Requires-Dist: pywinauto==0.6.9
+Requires-Dist: pyyaml==6.0.3
+Requires-Dist: ruamel-yaml==0.18.16
+Requires-Dist: structlog==25.5.0
+Requires-Dist: uiautomator2==3.5.2
+Provides-Extra: dev
+Requires-Dist: pre-commit==4.6.1; extra == 'dev'
+Requires-Dist: pytest-asyncio==1.3.0; extra == 'dev'
+Requires-Dist: pytest==9.0.3; extra == 'dev'
+Requires-Dist: ruff==0.16.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/logo-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="docs/assets/logo-light.svg">
+    <img alt="FSQ — Fully Self Quality" src="docs/assets/logo-light.svg" width="320">
+  </picture>
+</p>
+
+<h3 align="center">Evidence-first AI UI automation you can inspect, replay, and verify.</h3>
+
+<p align="center">
+  <a href="https://github.com/microsoft/FSQ/actions/workflows/ci.yml"><img src="https://github.com/microsoft/FSQ/actions/workflows/ci.yml/badge.svg" alt="CI status"></a>
+  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.11%2B-blue" alt="Python 3.11 or newer"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-yellow.svg" alt="MIT license"></a>
+  <img src="https://img.shields.io/badge/status-alpha-orange" alt="Alpha status">
+</p>
+
+<p align="center">
+  <a href="#five-minute-quickstart">Quickstart</a> ·
+  <a href="README.zh-CN.md">中文</a> ·
+  <a href="#coding-agent-workflow">Coding agents</a> ·
+  <a href="#how-fsq-works">How it works</a> ·
+  <a href="#supported-platforms">Platforms</a> ·
+  <a href="docs/getting-started.md">Documentation</a> ·
+  <a href="CONTRIBUTING.md">Contributing</a>
+</p>
+
+> [!IMPORTANT]
+> FSQ v0.1.0 is an alpha release. It is ready for evaluation and contribution, but public APIs and Case authoring details may evolve before 1.0. See [support and stability](docs/support-and-stability.md).
+
+FSQ turns a natural-language UI goal into an observable automation run, saves screenshots, UI snapshots, events, and reports as evidence, and can turn successful actions into a reviewable Case for deterministic replay. It uses Playwright, uiautomator2, pywinauto, and Appium as platform backends; it does not replace or install their host prerequisites.
+
+## Run existing Cases without an LLM
+
+Use FSQ like a test harness once a Case exists. Run history and offline reports do **not** require a configured LLM Provider. Strict replay is also provider-free unless the authored Case contains an AI assertion.
+
+```bash
+python -m pip install fsq-agent
+fsq init --platform web --browser-channel chrome
+# Store reviewed Case assets in your repo, for example: cases/web/*.fsq.yaml
+fsq case test --platform web cases/web/YOUR_CASE.fsq.yaml
+fsq runs show RUN_ID --open
+```
+
+## Create Cases with AI
+
+Configure an LLM Provider, then use `fsq case create --platform web --goal "..."` when you want FSQ to operate the real UI and create a reviewable `.fsq.yaml` Case from the successful Run. Coding agents should provide the goal and context; FSQ proves the path through live execution and evidence.
+
+## See FSQ in action
+
+Watch FSQ turn a natural-language goal into live UI execution, captured evidence, a reviewable Case, and deterministic replay.
+
+https://github.com/user-attachments/assets/aa9d0a12-2f93-4894-8349-52a013424939
+
+<p align="center">
+  <a href="https://youtu.be/QqCahxGDdS0">Watch the full demo on YouTube</a>
+</p>
+
+<p align="center">
+  <img src="docs/assets/fsq-workflow.svg" alt="FSQ workflow: describe a goal, execute once, capture evidence, verify, review a Case, and replay deterministically" width="880">
+</p>
+
+## Why FSQ
+
+- **Inspect the facts.** Every run keeps screenshots, normalized UI snapshots, ordered events, metadata, and reports together.
+- **Separate exploration from regression.** AI can explore a goal; reviewed YAML Cases replay authored actions deterministically.
+- **Use one workflow across UI surfaces.** Web, Android, Windows, and macOS share the same Case, evidence, Run, and readiness concepts.
+- **Keep control local.** Workspaces, evidence, Provider configuration, and the Control Plane are local by default.
+
+FSQ complements platform automation libraries. Playwright, uiautomator2, pywinauto, and Appium perform platform interaction; FSQ adds goal-driven execution, a shared Case format, evidence capture, verification, Run history, and a local Control Plane.
+
+## Product tour
+
+| Describe a goal | Inspect evidence | Review a candidate Case |
+|---|---|---|
+| <img src="docs/media/01-describe-goal.png" alt="FSQ Control Plane goal entry for a public TodoMVC workflow" width="280"> | <img src="docs/media/03-capture-evidence.png" alt="FSQ evidence view showing persisted UI state from the run" width="280"> | <img src="docs/media/04-generate-candidate.png" alt="FSQ Run-local candidate Case generated from execution facts" width="280"> |
+
+See the remaining approved screenshots in [release media](docs/media/README.md).
+
+## Five-minute quickstart
+
+This public Web example uses [TodoMVC](https://todomvc.com/examples/react/dist/), requires an installed Chromium-family browser, and writes all project data locally. Steps 1-3 exercise the provider-free harness path. A configured Provider is only needed for AI-driven Case creation or post-run suggestions.
+
+### 1. Install
+
+```bash
+python -m pip install fsq-agent
+```
+
+The base package includes Python dependencies for all four supported platforms. Browsers, applications, devices, ADB, and Appium services remain system prerequisites. FSQ never installs them during `init`.
+
+### 2. Create an empty Workspace
+
+```bash
+mkdir fsq-web-demo
+cd fsq-web-demo
+fsq init --platform web --browser-channel chrome
+fsq doctor
+```
+
+Workspace root selection is exact:
+
+- In an **empty current directory**, `fsq init` adopts that directory as the Workspace root.
+- In a **non-empty current directory**, it creates an absent `<current-directory>/<workspace-name>` child. Use `--name NAME` to choose that name, then change into the child directory for Workspace commands.
+- Other CLI commands never search parent directories; run them from the exact registered Workspace root.
+
+### 3. Replay the public example without a planning LLM
+
+Download the current [`examples/web/example-domain.fsq.yaml`](examples/web/example-domain.fsq.yaml) into the Workspace and run it:
+
+```bash
+mkdir -p cases/web
+curl --fail --location --output cases/web/example-domain.fsq.yaml \
+  https://raw.githubusercontent.com/microsoft/FSQ/main/examples/web/example-domain.fsq.yaml
+fsq case test --platform web cases/web/example-domain.fsq.yaml
+fsq runs list --platform web
+```
+
+### 4. Explore with AI
+
+Configure one supported user-level Provider from any directory:
+
+```bash
+fsq providers configure github_copilot
+fsq providers status
+```
+
+Then return to the Workspace:
+
+```bash
+fsq case create --platform web \
+  --goal "Open https://example.com and verify the Example Domain heading is visible."
+
+fsq case test --platform web --suggest cases/web/example-domain.fsq.yaml
+fsq runs show RUN_ID --open
+```
+
+`--suggest` executes the source Case exactly once, then asks AI to analyze only the persisted Case, report, and evidence. Suggestions and an optional candidate Case remain inside that Run; the source Case is not modified.
+
+### 5. Open the local Control Plane
+
+```bash
+fsq ui
+```
+
+The installed wheel includes the compiled frontend. It listens on `127.0.0.1:8879` by default and does not require Node.js at runtime.
+
+## Coding agent workflow
+
+Coding agents should not guess UI action steps or hand-author final Case YAML from code context alone. They should understand the product change, provide a precise goal to FSQ, and let FSQ operate the real UI before a Case is reviewed and committed.
+
+```bash
+# 1. Ask FSQ to prove a goal against the live UI and record evidence.
+fsq case create --platform web \
+  --goal "Open https://example.com and verify the Example Domain heading is visible."
+
+# 2. Inspect the generated Run and candidate Case.
+fsq runs list --platform web
+fsq runs show RUN_ID
+fsq runs logs RUN_ID
+
+# 3. Replay the reviewed generated Case deterministically before committing it.
+fsq case test --platform web cases/web/RUN_ID.fsq.yaml
+```
+
+The durable asset is the reviewed `.fsq.yaml` Case. The proof lives in `.fsq/runs/<platform>/<run-id>/` as events, screenshots, UI snapshots, evidence manifests, and reports. The strict replay path is provider-free, so CI and coding agents can verify committed Cases without configuring another LLM.
+
+## How FSQ works
+
+```text
+Goal ──► AI exploration ──► evidence ──► verification ──► reviewable Case
+                                                          │
+Reviewed Case ──► deterministic replay ──► fresh evidence ─┘
+```
+
+Dynamic execution and deterministic replay share platform Harnesses and evidence contracts. The original execution result is immutable; later suggestion analysis cannot rewrite it or perform another UI execution. Implementation-level architecture and behavior are defined by the root and module `SPEC.md` files.
+
+## Supported platforms
+
+| Platform | Interaction backend | Host prerequisites |
+|---|---|---|
+| Web | Playwright | A supported installed Chromium-family channel |
+| Android | uiautomator2 | ADB and an online authorized device |
+| Windows | pywinauto | Windows and an existing application |
+| macOS | Appium Mac2 | macOS, an existing application, and a reachable Appium service |
+
+All Python backend packages are installed with `fsq-agent`; platform applications and host services are not. Run `fsq doctor` from the exact Workspace root for actionable readiness results.
+
+Platform target options for `fsq init`:
+
+| Platform | Required target input |
+|---|---|
+| Android | `--app-id APP_ID` |
+| Web | `--browser-channel CHANNEL`; optional `--browser-executable-path FILE` |
+| Windows | `--app-path PATH`; optional `--window-title-re`, `--launch-args` |
+| macOS | At least one of `--bundle-id` or `--app-path` |
+
+## Runs and local data
+
+```text
+<workspace-root>/
+  .fsq/config/config.<platform>.yaml
+  .fsq/runs/<platform>/<run-id>/
+  cases/<platform>/
+  knowledge/<platform>/
+```
+
+Use `fsq runs list`, `fsq runs show RUN_ID`, and `fsq runs logs RUN_ID`. `fsq runs show RUN_ID --open` creates an offline static HTML report without calling a Provider or operating the UI. Evidence can contain visible application data; review it before sharing. Do not commit `.fsq`, credentials, reports, screenshots, or private target data.
+
+Provider configuration is stored under `~/.fsq` and shared by the CLI and local Control Plane. Supported first-release Providers are GitHub Copilot and Azure OpenAI.
+
+## Documentation
+
+| Resource | Purpose |
+|---|---|
+| [中文 README](README.zh-CN.md) | Chinese overview, quickstart, and release links |
+| [Getting started](docs/getting-started.md) | Installation, Workspace rules, first Web run, and next commands |
+| [中文快速开始](docs/getting-started.zh-CN.md) | Chinese installation and first-run guide |
+| [CLI reference](docs/cli-reference.md) | Current public command families and output modes |
+| [FSQ Case format](docs/case-format.md) | Case structure and a validated public example |
+| [Platform prerequisites](docs/platform-prerequisites.md) | Web, Android, Windows, and macOS host setup boundaries |
+| [Support and stability](docs/support-and-stability.md) | Alpha scope, compatibility, privacy, and support expectations |
+
+## Contributing
+
+Contributions are welcome across documentation, Cases, platform Harnesses, evidence, verification, and developer experience. Start with [CONTRIBUTING.md](CONTRIBUTING.md), follow the [Code of Conduct](CODE_OF_CONDUCT.md), and report vulnerabilities privately through [SECURITY.md](SECURITY.md).
+
+## License
+
+[MIT](LICENSE) — Copyright (c) Microsoft Corporation.

fsq_agent-0.1.0/README.md

@@ -0,0 +1,230 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/logo-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="docs/assets/logo-light.svg">
+    <img alt="FSQ — Fully Self Quality" src="docs/assets/logo-light.svg" width="320">
+  </picture>
+</p>
+
+<h3 align="center">Evidence-first AI UI automation you can inspect, replay, and verify.</h3>
+
+<p align="center">
+  <a href="https://github.com/microsoft/FSQ/actions/workflows/ci.yml"><img src="https://github.com/microsoft/FSQ/actions/workflows/ci.yml/badge.svg" alt="CI status"></a>
+  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.11%2B-blue" alt="Python 3.11 or newer"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-yellow.svg" alt="MIT license"></a>
+  <img src="https://img.shields.io/badge/status-alpha-orange" alt="Alpha status">
+</p>
+
+<p align="center">
+  <a href="#five-minute-quickstart">Quickstart</a> ·
+  <a href="README.zh-CN.md">中文</a> ·
+  <a href="#coding-agent-workflow">Coding agents</a> ·
+  <a href="#how-fsq-works">How it works</a> ·
+  <a href="#supported-platforms">Platforms</a> ·
+  <a href="docs/getting-started.md">Documentation</a> ·
+  <a href="CONTRIBUTING.md">Contributing</a>
+</p>
+
+> [!IMPORTANT]
+> FSQ v0.1.0 is an alpha release. It is ready for evaluation and contribution, but public APIs and Case authoring details may evolve before 1.0. See [support and stability](docs/support-and-stability.md).
+
+FSQ turns a natural-language UI goal into an observable automation run, saves screenshots, UI snapshots, events, and reports as evidence, and can turn successful actions into a reviewable Case for deterministic replay. It uses Playwright, uiautomator2, pywinauto, and Appium as platform backends; it does not replace or install their host prerequisites.
+
+## Run existing Cases without an LLM
+
+Use FSQ like a test harness once a Case exists. Run history and offline reports do **not** require a configured LLM Provider. Strict replay is also provider-free unless the authored Case contains an AI assertion.
+
+```bash
+python -m pip install fsq-agent
+fsq init --platform web --browser-channel chrome
+# Store reviewed Case assets in your repo, for example: cases/web/*.fsq.yaml
+fsq case test --platform web cases/web/YOUR_CASE.fsq.yaml
+fsq runs show RUN_ID --open
+```
+
+## Create Cases with AI
+
+Configure an LLM Provider, then use `fsq case create --platform web --goal "..."` when you want FSQ to operate the real UI and create a reviewable `.fsq.yaml` Case from the successful Run. Coding agents should provide the goal and context; FSQ proves the path through live execution and evidence.
+
+## See FSQ in action
+
+Watch FSQ turn a natural-language goal into live UI execution, captured evidence, a reviewable Case, and deterministic replay.
+
+https://github.com/user-attachments/assets/aa9d0a12-2f93-4894-8349-52a013424939
+
+<p align="center">
+  <a href="https://youtu.be/QqCahxGDdS0">Watch the full demo on YouTube</a>
+</p>
+
+<p align="center">
+  <img src="docs/assets/fsq-workflow.svg" alt="FSQ workflow: describe a goal, execute once, capture evidence, verify, review a Case, and replay deterministically" width="880">
+</p>
+
+## Why FSQ
+
+- **Inspect the facts.** Every run keeps screenshots, normalized UI snapshots, ordered events, metadata, and reports together.
+- **Separate exploration from regression.** AI can explore a goal; reviewed YAML Cases replay authored actions deterministically.
+- **Use one workflow across UI surfaces.** Web, Android, Windows, and macOS share the same Case, evidence, Run, and readiness concepts.
+- **Keep control local.** Workspaces, evidence, Provider configuration, and the Control Plane are local by default.
+
+FSQ complements platform automation libraries. Playwright, uiautomator2, pywinauto, and Appium perform platform interaction; FSQ adds goal-driven execution, a shared Case format, evidence capture, verification, Run history, and a local Control Plane.
+
+## Product tour
+
+| Describe a goal | Inspect evidence | Review a candidate Case |
+|---|---|---|
+| <img src="docs/media/01-describe-goal.png" alt="FSQ Control Plane goal entry for a public TodoMVC workflow" width="280"> | <img src="docs/media/03-capture-evidence.png" alt="FSQ evidence view showing persisted UI state from the run" width="280"> | <img src="docs/media/04-generate-candidate.png" alt="FSQ Run-local candidate Case generated from execution facts" width="280"> |
+
+See the remaining approved screenshots in [release media](docs/media/README.md).
+
+## Five-minute quickstart
+
+This public Web example uses [TodoMVC](https://todomvc.com/examples/react/dist/), requires an installed Chromium-family browser, and writes all project data locally. Steps 1-3 exercise the provider-free harness path. A configured Provider is only needed for AI-driven Case creation or post-run suggestions.
+
+### 1. Install
+
+```bash
+python -m pip install fsq-agent
+```
+
+The base package includes Python dependencies for all four supported platforms. Browsers, applications, devices, ADB, and Appium services remain system prerequisites. FSQ never installs them during `init`.
+
+### 2. Create an empty Workspace
+
+```bash
+mkdir fsq-web-demo
+cd fsq-web-demo
+fsq init --platform web --browser-channel chrome
+fsq doctor
+```
+
+Workspace root selection is exact:
+
+- In an **empty current directory**, `fsq init` adopts that directory as the Workspace root.
+- In a **non-empty current directory**, it creates an absent `<current-directory>/<workspace-name>` child. Use `--name NAME` to choose that name, then change into the child directory for Workspace commands.
+- Other CLI commands never search parent directories; run them from the exact registered Workspace root.
+
+### 3. Replay the public example without a planning LLM
+
+Download the current [`examples/web/example-domain.fsq.yaml`](examples/web/example-domain.fsq.yaml) into the Workspace and run it:
+
+```bash
+mkdir -p cases/web
+curl --fail --location --output cases/web/example-domain.fsq.yaml \
+  https://raw.githubusercontent.com/microsoft/FSQ/main/examples/web/example-domain.fsq.yaml
+fsq case test --platform web cases/web/example-domain.fsq.yaml
+fsq runs list --platform web
+```
+
+### 4. Explore with AI
+
+Configure one supported user-level Provider from any directory:
+
+```bash
+fsq providers configure github_copilot
+fsq providers status
+```
+
+Then return to the Workspace:
+
+```bash
+fsq case create --platform web \
+  --goal "Open https://example.com and verify the Example Domain heading is visible."
+
+fsq case test --platform web --suggest cases/web/example-domain.fsq.yaml
+fsq runs show RUN_ID --open
+```
+
+`--suggest` executes the source Case exactly once, then asks AI to analyze only the persisted Case, report, and evidence. Suggestions and an optional candidate Case remain inside that Run; the source Case is not modified.
+
+### 5. Open the local Control Plane
+
+```bash
+fsq ui
+```
+
+The installed wheel includes the compiled frontend. It listens on `127.0.0.1:8879` by default and does not require Node.js at runtime.
+
+## Coding agent workflow
+
+Coding agents should not guess UI action steps or hand-author final Case YAML from code context alone. They should understand the product change, provide a precise goal to FSQ, and let FSQ operate the real UI before a Case is reviewed and committed.
+
+```bash
+# 1. Ask FSQ to prove a goal against the live UI and record evidence.
+fsq case create --platform web \
+  --goal "Open https://example.com and verify the Example Domain heading is visible."
+
+# 2. Inspect the generated Run and candidate Case.
+fsq runs list --platform web
+fsq runs show RUN_ID
+fsq runs logs RUN_ID
+
+# 3. Replay the reviewed generated Case deterministically before committing it.
+fsq case test --platform web cases/web/RUN_ID.fsq.yaml
+```
+
+The durable asset is the reviewed `.fsq.yaml` Case. The proof lives in `.fsq/runs/<platform>/<run-id>/` as events, screenshots, UI snapshots, evidence manifests, and reports. The strict replay path is provider-free, so CI and coding agents can verify committed Cases without configuring another LLM.
+
+## How FSQ works
+
+```text
+Goal ──► AI exploration ──► evidence ──► verification ──► reviewable Case
+                                                          │
+Reviewed Case ──► deterministic replay ──► fresh evidence ─┘
+```
+
+Dynamic execution and deterministic replay share platform Harnesses and evidence contracts. The original execution result is immutable; later suggestion analysis cannot rewrite it or perform another UI execution. Implementation-level architecture and behavior are defined by the root and module `SPEC.md` files.
+
+## Supported platforms
+
+| Platform | Interaction backend | Host prerequisites |
+|---|---|---|
+| Web | Playwright | A supported installed Chromium-family channel |
+| Android | uiautomator2 | ADB and an online authorized device |
+| Windows | pywinauto | Windows and an existing application |
+| macOS | Appium Mac2 | macOS, an existing application, and a reachable Appium service |
+
+All Python backend packages are installed with `fsq-agent`; platform applications and host services are not. Run `fsq doctor` from the exact Workspace root for actionable readiness results.
+
+Platform target options for `fsq init`:
+
+| Platform | Required target input |
+|---|---|
+| Android | `--app-id APP_ID` |
+| Web | `--browser-channel CHANNEL`; optional `--browser-executable-path FILE` |
+| Windows | `--app-path PATH`; optional `--window-title-re`, `--launch-args` |
+| macOS | At least one of `--bundle-id` or `--app-path` |
+
+## Runs and local data
+
+```text
+<workspace-root>/
+  .fsq/config/config.<platform>.yaml
+  .fsq/runs/<platform>/<run-id>/
+  cases/<platform>/
+  knowledge/<platform>/
+```
+
+Use `fsq runs list`, `fsq runs show RUN_ID`, and `fsq runs logs RUN_ID`. `fsq runs show RUN_ID --open` creates an offline static HTML report without calling a Provider or operating the UI. Evidence can contain visible application data; review it before sharing. Do not commit `.fsq`, credentials, reports, screenshots, or private target data.
+
+Provider configuration is stored under `~/.fsq` and shared by the CLI and local Control Plane. Supported first-release Providers are GitHub Copilot and Azure OpenAI.
+
+## Documentation
+
+| Resource | Purpose |
+|---|---|
+| [中文 README](README.zh-CN.md) | Chinese overview, quickstart, and release links |
+| [Getting started](docs/getting-started.md) | Installation, Workspace rules, first Web run, and next commands |
+| [中文快速开始](docs/getting-started.zh-CN.md) | Chinese installation and first-run guide |
+| [CLI reference](docs/cli-reference.md) | Current public command families and output modes |
+| [FSQ Case format](docs/case-format.md) | Case structure and a validated public example |
+| [Platform prerequisites](docs/platform-prerequisites.md) | Web, Android, Windows, and macOS host setup boundaries |
+| [Support and stability](docs/support-and-stability.md) | Alpha scope, compatibility, privacy, and support expectations |
+
+## Contributing
+
+Contributions are welcome across documentation, Cases, platform Harnesses, evidence, verification, and developer experience. Start with [CONTRIBUTING.md](CONTRIBUTING.md), follow the [Code of Conduct](CODE_OF_CONDUCT.md), and report vulnerabilities privately through [SECURITY.md](SECURITY.md).
+
+## License
+
+[MIT](LICENSE) — Copyright (c) Microsoft Corporation.