flowglyph 0.1.0__tar.gz

flowglyph-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+.coverage
+coverage.xml
+htmlcov/
+.pytest_cache/
+.ruff_cache/
+.flowglyph/
+*.ledger.sqlite
+node_modules/
+scripts/dist/
+.DS_Store
+examples/*/out/

flowglyph-0.1.0/CHANGELOG.md

@@ -0,0 +1,252 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+Nothing yet.
+
+## [0.1.0] - 2026-11-07
+
+The first release.
+
+### Added
+
+- `HOWTO.md`: every tool, what it does and how to use it, checked against the CLI by the
+  test suite.
+- An animated walkthrough (`docs/assets/walkthrough.gif` and `.mp4`): the six things FlowGlyph
+  does, each introduced on its own and shown on one folder, plus one short clip per use case on
+  its page in `docs/use-cases/`. Rendered frame by frame from `scripts/walkthrough/` by
+  `make walkthrough`; every line it shows is real output.
+- README: the handover folder of a client taken to a new robot in six commands, with the real
+  output of each; `docs/use-cases/`: the same six as stories of their own, with who each is
+  for and how to tell it. Their commands are checked against the CLI by the test suite.
+- Automation IR (`Capability`, `Workflow`, `Effects`, `Idempotency`) with JSON Schemas.
+- UiPath adapter: typed arguments with defaults and annotations, a taxonomy of activities with
+  tri-state effects, workflow graphs with branches, transitive effects through invocations.
+- Catalog with deterministic `save`/`load_catalog`, BM25 search, L0 cards, Markdown cards and
+  an index, a lock file with automatic semver bumps, and `flowglyph.overrides.yaml`.
+- `flowglyph` command line: `extract`, `validate`, `diff`, `inspect` and `search`.
+- README with Excalidraw diagrams rendered to light and dark SVG by `make diagrams`.
+- OpenAPI 3.0 and 3.1 adapter: parameters and bodies as one input schema, local `$ref`
+  resolution with recursion cut-off, effects and idempotency from HTTP semantics and
+  `Idempotency-Key` headers, OAuth scopes and error responses.
+- MCP gateway (`flowglyph serve`): L0/L1/L2 discovery tools, one tool per capability or
+  search-only exposure, JSON Schema validation, YAML policies with allow, deny and approval,
+  an SQLite idempotency ledger with atomic claims and TTL, an audit log without argument
+  values, and `flowglyph approve` / `approvals` for people.
+- Planner (`flowglyph plan`): BM25 shortlist, a plan proposed by Claude with structured output
+  and server-side refusal fallbacks, and a deterministic resolver that rejects invented
+  capabilities and broken references and reports missing capabilities as gaps.
+- `flowglyph plan` reads the requirements from the document the process arrived in: a PDF, a
+  Word or Excel file, a CSV, text or Markdown, or a folder holding all of them, through the new
+  `flowglyph[documents]` extra (`flowglyph.planner.documents.read_requirements` from Python).
+- The planner works with any provider. `--via` selects the Anthropic API, a signed-in coding
+  assistant run headless (`claude-code`, `codex`, `gemini`, `cursor`, or any tool described with
+  a `CommandSpec`), any OpenAI-compatible server (OpenAI, Ollama, vLLM, LM Studio, OpenRouter)
+  through the standard library, or a plugin registered under `flowglyph.planners`. Plans use a
+  strict JSON Schema that all of them accept.
+- SAP adapter (`--adapter sap`): reads OData V2 and V4 `$metadata` (EDMX) from SAP S/4HANA,
+  SAP Gateway or SAP BTP. One capability per operation the service allows, honouring
+  `sap:creatable`/`updatable`/`deletable` and the V4 Capabilities vocabulary, with typed keys and
+  bodies, SAP labels as descriptions, function imports, functions and bound actions.
+- Extraction from whole trees and git repositories: `flowglyph extract <folder|file|git URL>`
+  reads every project and document it finds, records the origin and commit in the lock, and
+  `--adapter` limits it to one source type.
+- `flowglyph idempotency`: the catalog and nothing else, one row per function with its effects,
+  idempotency and a status (`safe`, `keyed`, `declared`, `review`, `n/a`), filterable by kind, provider,
+  side effects or pending review, as a table, Markdown, CSV or JSON. Also `flowglyph.report`.
+- `flowglyph adapters` lists the source formats available, plugins included.
+- `flowglyph wiki build` and `wiki lint`: an LLM wiki of the catalog in the shape of Karpathy's
+  "LLM Wiki". Generated pages per capability, category and source with backlinks, an index, an
+  overview, an append-only log of ingests and lint passes, an `AGENTS.md` schema for the LLM that
+  maintains it, and Notes sections that survive every rebuild. Lint reports idempotency to
+  review, invocations outside the sources, orphan workflows, broken links and retired pages.
+- The UiPath taxonomy covers cloud, infrastructure, directory and SaaS connector packages (Azure,
+  AWS, Google Cloud, Citrix, Hyper-V, VMware, Active Directory, Jira...) and derives effects from
+  the verb in an activity's name (`Get`, `Create`, `Set`, `Delete`, `...Scope`) where the category
+  alone cannot tell. On UiPath's IT automation solutions, unclassified activities drop from 118
+  to 1 of 172.
+- Repository URLs that point at a folder download only that folder (sparse checkout), and the
+  checkout is named after the repository.
+- Services or APIs published twice in one source, such as the same SAP service as OData V2 and
+  V4, keep separate ids. SAP metadata that uses the `sap:` prefix without declaring it is read.
+- SAP Cloud Integration adapter (`--adapter sap-cpi`): iFlows exported as `.zip` (read in
+  memory, with size and compression limits) or unpacked. One capability per endpoint, effects from
+  receivers and steps, ProcessDirect calls resolved across iFlows (from steps, message end events,
+  local processes and exception subprocesses), idempotency declared by the iFlow itself, and a
+  design review whose findings reach `wiki lint`. Parameter values are never read.
+- `wiki lint` lists the notes adapters attach to capabilities.
+- `examples/sap-integration`: OData services and Cloud Integration iFlows taken through the
+  report, overrides, the wiki and the gateway, with real output. `make examples` regenerates the
+  committed example catalogs, and a test fails when they are out of date.
+- Executors (ADR-0011): `flowglyph serve --connections flowglyph.connections.yaml` runs
+  capabilities for real instead of dry-running them. An `http` connection calls OpenAPI
+  operations, placing each argument in the path, query, headers, cookies or body; an `odata`
+  connection calls SAP OData V2 and V4 services with CSRF handling, OData literals and SAP error
+  messages; a `uipath` connection starts the published process of a UiPath project as an
+  Orchestrator job and waits for its output arguments. Authentication: none, bearer, basic, a
+  header, or OAuth client credentials, with every secret read from a named environment variable.
+  Redirects are never followed and only `http(s)` URLs are called.
+- BPMN adapter (`--adapter bpmn`, ADR-0012): BPMN 2.0 processes with Camunda 7 (forms, external
+  task topics, classes, expressions, decision references) and Camunda 8 (job types, called
+  processes) extensions. Start forms become typed inputs, gateways keep their conditions and
+  default flows, boundary events become labelled edges, call activities link processes across
+  files, and missing implementations and default flows are reported.
+- n8n adapter (`--adapter n8n`): workflows exported one per file or as a list. Webhooks become
+  callable `POST /webhook/...` capabilities, sub-workflows keep their declared inputs, schedules
+  their cron expression, `Execute Workflow` nodes link workflows by id, name or file, effects come
+  from each node's method or operation, and credentials are recorded by name.
+- SAP Build Process Automation adapter (`--adapter sbpa`): `.mtar` exports and unpacked projects.
+  Processes take their inputs from the start form's schema and invoke their automations and
+  decisions in the graph, with SAP's own branch conditions; automations and decisions are
+  capabilities of their own. Archives are read in memory with size and compression limits,
+  shared with the SAP Cloud Integration adapter.
+- Compilers (`flowglyph compile`, ADR-0013): any workflow graph, planned or extracted, compiles
+  into BPMN 2.0 with a diagram, plain or with the Camunda 7 (external task topics) or Camunda 8
+  (job types) extensions an engine needs, or into a UiPath Studio workflow: a Sequence for a
+  straight line, a Flowchart of FlowSteps and FlowDecisions when it branches, Invoke Workflow
+  File for UiPath workflows with their arguments listed, and a Comment for anything else. What
+  cannot be carried over exactly, such as conditions in another expression language, is
+  reported. Compiled BPMN reads back through the BPMN adapter into the same graph.
+- Enrichment (`flowglyph enrich`, ADR-0014): a model describes capabilities whose source left
+  no description, only a placeholder or the adapter's boilerplate, and gives every capability
+  its business verb, entity and domain. It works through any planner backend, sees only what the
+  catalog knows (never sources or configuration), and answers for unknown ids are dropped.
+  Answers are cached in `flowglyph.enrichment.json` by source hash and reapplied by `extract`
+  before versioning, so reruns change nothing. IR 0.4.0 adds `Capability.generated`, the fields
+  a model wrote; cards say so. Idempotency is never enriched.
+- Context for coding agents (`flowglyph context`, ADR-0015): per UiPath project, an `AGENTS.md`
+  and `.claude/rules/project-context.md` in the sections UiPath's own discovery agent uses, but
+  read from the sources rather than written by a model, plus what no model can tell by reading:
+  effects, retry safety and the call tree. One activity card per activity type, with a XAML
+  template from the project's richest use of it: settings kept, values as `[placeholders]`, the
+  namespaces to declare. Notes are kept on every run, and files FlowGlyph did not write are not
+  replaced without `--force`.
+- The UiPath adapter records that template on each activity type (`x-xaml-template`); it is
+  documentation, so it never moves a version.
+- An Agent Skill (`flowglyph skill`) teaches coding agents when and how to use FlowGlyph, and
+  the repository is a plugin for Claude Code, Codex, Cursor and Gemini CLI.
+- `docs/guide.md`: how to use every feature, in the order you would use them, with samples to
+  follow from a clone. A test checks that every command and option it shows exists.
+- Every planner backend can now answer with any pydantic model (`StructuredModel.answer`), not
+  only a plan, so new uses of a model need no new backend.
+- `flowglyph.extract(..., refine=...)` applies a step after overrides and before versioning.
+- `examples/uipath-reframework`: UiPath's ReFrameWork template through the call tree, the
+  idempotency report, overrides, a change made in Studio and its versions, the wiki and the
+  gateway, with real output.
+- Documentation: an architecture guide by bounded context, a glossary, decision records 0005 to
+  0010, and guides with tested examples for writing an adapter or a planner backend.
+
+### Changed
+
+- The idempotency report shows `pure` for a capability without effects, as `inspect`, the wiki
+  and the context files do; `none` is only ever an idempotency mode.
+- The `Else` of an `If` is guarded by `otherwise`, like a BPMN default flow, instead of
+  `not (<condition>)`; `Workflow.simulate` takes an `otherwise` edge when no other condition
+  of its source holds.
+- Lock files record the shape of every parameter (types, required, nested properties and
+  items) and leave defaults out, so the format changed; catalogs are re-versioned from 1.0.0
+  on the next `extract`.
+- `flowglyph` also exports `Parameter`, `Semantics`, `Security`, `Source`, `Extraction`,
+  `Diagnostic`, `Change`, `Bump` and `export_json_schemas`, everything needed to build a
+  capability or read what changed.
+- IR 0.3.0 (ADR-0005): `Capability` gains typed `trigger`, `entry_point`, `configuration`,
+  `used_in` and `deprecated` fields instead of prefixed strings in `tags`. Presentation moves out
+  of the IR into `flowglyph.views`: `effects_code`, `retry_advice` and `l0_card` replace
+  `Effects.code()`, `Idempotency.advice()` and `Capability.card()`.
+- Marking a capability deprecated is now a minor version bump, as semver requires.
+- `flowglyph.catalog` is a package (`lock`, `versioning`, `overrides`, `extraction`, `model`);
+  its public names are unchanged.
+- The gateway applies deny rules before validating arguments, so an agent is not asked to fix
+  the arguments of a call it may not make.
+- The command line is split into one module per context; `flowglyph.cli.main:app` is unchanged.
+- IR 0.2.0: nodes have a `join` (`all` or `any`) and skipped steps propagate, so a workflow
+  says what runs after an optional step. `Workflow.simulate` evaluates the rules. The UiPath
+  adapter marks branch merges as `any`; the planner chooses a join per step and warns about
+  steps that would be skipped with an optional predecessor.
+- Dependency floors are the oldest versions the code works with (`pydantic>=2.12`,
+  `pyyaml>=6.0.1`, `typer>=0.19`, `rich>=13`, `mcp>=2.1`, `jsonschema>=4.18`,
+  `anthropic>=2.0`) instead of the versions locked for development.
+- Connections must use `https://`; a connection that sets `allow_insecure: true` may use
+  `http://`. Every address, OAuth token URLs included, is checked when the file is loaded.
+- The ledger keeps the arguments of each run, so `flowglyph approvals` shows what a person
+  approves, and `flowglyph approve` records an `approve` audit event with the user's name.
+  Every audit record has an `actor` field, `null` when the agent acted.
+
+### Changed
+
+- Pipeline diagram: LLM enrichment drawn as shipped, the planner's document inputs, and the
+  coding-agent context as an output with its own consumer; token-flow diagram: an L1 card is
+  about 400 tokens, measured.
+
+### Fixed
+
+- UiPath: a `TryCatch` is now a decision whose handlers are reached `on <ExceptionType>` and
+  whose `Finally` follows every branch, and a `Switch` a decision with one guarded edge per
+  case; both were flattened into a sequence, so error handlers and exclusive cases looked like
+  the happy path. An `If` whose branches hold nothing is no longer kept as a decision.
+- n8n, SAP Build Process Automation, BPMN and SAP Cloud Integration: two branches that met
+  again in a folded node kept only one condition; the walk is now shared and keeps both.
+- UiPath: the annotation of a workflow's top-level activity described the activity type
+  (`Sequence`, `Flowchart`) instead of only the workflow.
+- Versioning: an input narrowed (a type or `null` no longer accepted, a nested property
+  dropped), an output widened, newly nullable or no longer required, and a capability that
+  stops being invocable are now major changes; they were minor. Wording changes anywhere in
+  a schema are a patch.
+- The planner accepted arguments of the wrong type: a string output bound to an integer input,
+  a literal `"yes"` for a boolean, a string workflow input for a number. The resolver now compares
+  the type of every workflow input, step output and literal with the input it feeds and reports
+  each mismatch as a problem. `integer` fits `number`, `null` fits a nullable input, and `any`
+  on either side is not checked.
+- The three most likely first mistakes printed a traceback. A `--policy` file or requirements
+  document that does not exist, `--via anthropic` without `ANTHROPIC_API_KEY` (or an
+  `ant auth login` profile), and a `--via claude-code`, `codex`, `gemini` or `cursor` whose
+  command is not on PATH are now one `error:` line that says what to do, before anything runs.
+- XML sources that declare a DTD after the first 4 KiB, for example behind a long comment, are
+  refused like any other DTD.
+- The command line printed source text as Rich markup, so diagnostics lost expressions such as
+  `[in_target]`. Source text is now escaped.
+- The approval command the gateway suggests includes `--state` when the gateway keeps its state
+  elsewhere, and quotes its arguments for the shell.
+- The OpenAI-compatible planner refuses a base URL that is not `http` or `https`, so
+  `OPENAI_BASE_URL` cannot point the standard library at local files.
+- Catalogs, lock files, wikis and plans are written with LF line endings on every platform, so a
+  catalog saved on Windows is byte-identical to one saved on Linux or macOS.
+- Repositories read from a Windows path are cached under their own name instead of the whole
+  path, and git runs with long paths enabled, so deep repositories clone on Windows.
+- On Windows, command-line planner backends refuse a `.cmd` or `.bat` launcher when the
+  arguments it would receive contain cmd.exe syntax, such as the JSON Schema, instead of letting
+  cmd.exe cut them short or redirect them. Arguments without it, such as file paths, still work.
+- `flowglyph diff --fail-on major` failed whenever a capability was added. Additions are now a
+  minor change and removals stay major, so the check fails only on changes that break a caller.
+- Capabilities that cannot run on their own, such as UiPath activity types, were reported as
+  `review`, which no override could usefully settle. Their status is now `n/a`, in the report,
+  the CLI and wiki lint.
+- UiPath arguments of .NET reference types (strings, arrays, objects such as exceptions or queue
+  items) accept `null`, which is how `Nothing` reaches a workflow; the gateway refused the most
+  common call to the ReFrameWork's `SetTransactionStatus`. Value types such as `Int32` do not,
+  unless declared `Nullable`, and `Int16`, `Byte`, `Single`, `Guid` and `Char` get their JSON types.
+- An error that was not a `FlowGlyphError` raised by an executor escaped `Gateway.run`, leaving
+  the ledger row `running` until it expired and no audit line. Every run now ends as a result,
+  `failed` with the error text when the executor raised, and a `start` audit event is written
+  before executing.
+- A `--ref` that starts with `-` reached git as an option (`--upload-pack=...` ran a command).
+  Such refs are refused, and git is told where its options end before the remote and the URL.
+- An HTTP path argument of `..` called a different route; empty, `.` and `..` path values are
+  refused, and a header value with a line break fails cleanly instead of with a bare ValueError.
+- `import flowglyph.gateway` without the `[mcp]` extra failed with a bare `ModuleNotFoundError`;
+  it now says which extra to install.
+- Two capability ids that sanitise to the same MCP tool name collided and the last one won
+  silently; both now get a short hash suffix.
+- Argument validation checks string formats, so `format: uuid` (SAP `Edm.Guid`) rejects
+  anything that is not a UUID, and every OData literal emitted without quotes must match the
+  shape of its Edm type.
+- Capability titles, descriptions and cards lose control characters before they reach an MCP
+  client, and the server instructions say they are data from the sources, not instructions.
+
+[Unreleased]: https://github.com/afernandeztem/FlowGlyph/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/afernandeztem/FlowGlyph/releases/tag/v0.1.0

flowglyph-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,83 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at a.fernandez.tem@gmail.com. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq][FAQ]. Translations are available at [https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

flowglyph-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,249 @@
+# Contributing to FlowGlyph
+
+Thanks for taking the time to contribute. This document covers how to set up the project,
+the conventions the codebase follows, and how changes get merged.
+
+## Development setup
+
+You need [uv](https://docs.astral.sh/uv/) 0.13 or newer. Node 26 is only needed to
+regenerate the README diagrams.
+
+```bash
+git clone https://github.com/afernandeztem/FlowGlyph
+cd FlowGlyph
+make install   # uv sync --all-extras + pre-commit hooks
+make check     # ruff, pyright, pytest
+```
+
+Tests that call a real LLM are marked `llm` and skipped by default. `make test-llm` runs them
+with the backend named in `FLOWGLYPH_PLANNER` (`anthropic` by default, which needs an
+`ANTHROPIC_API_KEY`; `claude-code`, `codex`, `gemini` or `cursor` use that tool's own sign-in).
+Every run uses real model capacity.
+
+Before changing code, read [docs/guide.md](docs/guide.md) to see what FlowGlyph does from a
+user's side, [docs/architecture.md](docs/architecture.md) for how the code is divided and
+[docs/glossary.md](docs/glossary.md) for what its words mean.
+
+## Project layout
+
+| Path | What lives there |
+|---|---|
+| `src/flowglyph/ir.py` | The Automation IR models. Changing them is a spec change, see below. |
+| `src/flowglyph/views.py` | How the IR is shown: effects codes, retry advice, L0 cards. |
+| `src/flowglyph/sources.py` | Folders, files and git URLs resolved to local files. |
+| `src/flowglyph/adapters/` | One subpackage per source format. Adapters only produce IR. |
+| `src/flowglyph/catalog/` | Extraction, lock file and versioning, overrides, search, persistence. |
+| `src/flowglyph/report.py` | The idempotency report. |
+| `src/flowglyph/wiki.py` | The LLM wiki: build and lint. |
+| `src/flowglyph/gateway/` | MCP server, policy engine, idempotency ledger, audit log, executors. |
+| `src/flowglyph/planner/` | Requirements to workflow IR, and the backends that propose plans. |
+| `src/flowglyph/compilers/` | Workflow IR back to BPMN and UiPath XAML. |
+| `src/flowglyph/context.py` | Context files and activity cards for coding agents. |
+| `src/flowglyph/skill/SKILL.md` | The Agent Skill; `skills/flowglyph/SKILL.md` is a copy a test keeps identical. |
+| `src/flowglyph/cli/` | The `flowglyph` command: one module per context in `commands/`. |
+| `src/flowglyph/_internal/` | Private helpers. Not part of the public API. |
+| `tests/unit/` | Fast tests per module. `test_architecture.py` enforces the dependency rules. |
+| `tests/e2e/` | The command line and the MCP server, driven as a user or agent would. |
+| `tests/golden/` | Expected outputs. Regenerate with `pytest --update-golden` and review the diff. |
+| `tests/eval/` | Planner quality against a real model (`-m llm`). |
+| `tests/fixtures/` | Sample sources. Third-party ones keep their license next to them and in `NOTICE`. |
+| `docs/adr/` | Decision records: why things are the way they are. |
+
+## Code style
+
+The bar is code that reads as if one careful person wrote all of it.
+
+- English everywhere: code, docstrings, error messages, commit messages.
+- Google-style docstrings on public modules, classes and functions, only when they say
+  something the signature does not. Private helpers usually need none.
+- No inline comments that describe *what* a line does. A comment is allowed only to explain a
+  non-obvious *why*: a workaround, a spec reference, a deliberate trade-off.
+- No section banners. If a module needs sections, it needs to be split into modules.
+- No commented-out code, no emoji, no `TODO` without a linked issue.
+- Full names over abbreviations. `workflow`, not `wf`; `activity`, not `a`.
+- Data that crosses a module boundary is a typed model, never an anonymous `dict`.
+- Project exceptions derive from `FlowGlyphError`. Never catch bare `Exception`.
+- Keep functions small and single-purpose; ruff enforces the limits.
+
+`ruff check`, `ruff format --check` and `pyright` (strict) must pass. Pre-commit runs all
+three.
+
+## Changing the IR
+
+The IR is the project's contract with every adapter, catalog and agent that consumes it.
+Changes to `ir.py` need:
+
+1. An ADR in `docs/adr/` explaining the change and its migration path.
+2. An update to `docs/ir-spec.md` and the generated JSON Schemas (`make schemas`).
+3. A bump of `IR_VERSION` following semver: removing or renaming a field is a major change.
+
+## Writing an adapter
+
+An adapter translates one source format into IR. It is a class with a `name`, a `version`, and
+two methods; nothing to inherit. This one reads scheduled jobs from a `jobs.yaml` file:
+
+<!-- adapter-example -->
+```python
+import hashlib
+from pathlib import Path
+from typing import ClassVar
+
+import yaml
+
+from flowglyph import Capability, Effects, Trigger
+from flowglyph.adapters import Diagnostic, Extraction
+from flowglyph.ir import Source
+
+
+class JobsAdapter:
+    """Scheduled jobs listed in a `jobs.yaml` file."""
+
+    name: ClassVar[str] = "jobs"
+    version: ClassVar[str] = "0.1.0"
+
+    def detect(self, path: Path) -> bool:
+        """Whether `path` is, or contains, a `jobs.yaml`."""
+        return path.name == "jobs.yaml" or (path / "jobs.yaml").is_file()
+
+    def extract(self, path: Path) -> Extraction:
+        """One capability per job."""
+        file = path if path.is_file() else path / "jobs.yaml"
+        data = file.read_bytes()
+        source_hash = "sha256:" + hashlib.sha256(data).hexdigest()
+        capabilities: list[Capability] = []
+        diagnostics: list[Diagnostic] = []
+        for job in yaml.safe_load(data).get("jobs", []):
+            if "schedule" not in job:
+                message = f"{job['name']} has no schedule"
+                diagnostics.append(Diagnostic("warning", file.name, message))
+                continue
+            capabilities.append(
+                Capability(
+                    id=f"jobs/{job['name']}",
+                    kind="workflow",
+                    title=job["name"],
+                    description=job.get("description", ""),
+                    trigger=Trigger(kind="schedule", channel="cron", address=job["schedule"]),
+                    effects=Effects(),
+                    source=Source(
+                        provider=self.name,
+                        artifact=job["name"],
+                        location=file.name,
+                        source_hash=source_hash,
+                    ),
+                    invocable=False,
+                )
+            )
+        return Extraction(
+            capabilities=capabilities,
+            artifacts={file.name: source_hash},
+            diagnostics=diagnostics,
+        )
+```
+
+Register it from your own package, and `flowglyph extract --adapter jobs` finds it:
+
+```toml
+[project.entry-points."flowglyph.adapters"]
+jobs = "flowglyph_jobs:JobsAdapter"
+```
+
+In tests or scripts, `flowglyph.register_adapter("jobs", JobsAdapter)` does the same.
+
+When a tree can hold many sources (every UiPath project in a repository, say), also define
+`discover(root) -> list[Path]`; each path it returns is extracted on its own. Without it, the
+adapter receives `root` whole when `detect` accepts it.
+
+The rules every adapter follows:
+
+- **Deterministic and offline.** The same bytes always give the same `Extraction`: no network,
+  no LLM, no clock, no randomness. Sort what you emit.
+- **Sources are untrusted data.** Parse them; never execute, import or evaluate anything they
+  contain. Refuse XML that declares a DTD (built-in adapters use `_internal.xml.parse_xml`).
+  Read the names of externalized configuration, never its values.
+- **Say unknown when you do not know.** `Effects()` is unknown everywhere, and that is a better
+  answer than a guess. Use `yes` and `no` only for what the format guarantees.
+- **Declare only what the source declares.** Idempotency is `declared` only when the source
+  itself promises it; otherwise it is `inferred`, with an honest `confidence`.
+- **Facts go in fields, not tags.** Use `trigger`, `entry_point`, `configuration`, `used_in` and
+  `deprecated`; keep `tags` for the source's own free labels.
+- **Ids are stable.** An id never moves to a different operation, and does not change when a
+  file is reformatted. Prefix it with the adapter name.
+- **Report, do not fail.** Problems with one artifact become a `Diagnostic`; raise
+  `AdapterError` only when nothing can be read.
+- **Test with real samples.** Add fixtures under `tests/fixtures/` (with their license if they
+  are not yours), unit tests for each rule, and a golden test once the output is stable.
+
+## Adding a planner backend
+
+A planner backend proposes a plan; the resolver then checks it against the catalog, so a backend
+never has to be trusted. There are two ways to add one.
+
+**A coding assistant with a headless mode** needs only a `CommandSpec`: the command line to run,
+where the JSON Schema goes (`{schema}` or `{schema_file}`), and where the plan comes back (stdout,
+a key in a JSON envelope, or `{output_file}`). Built-in presets are in
+`src/flowglyph/planner/command.py`; add yours there and to `BUILT_IN` in `planner/backends.py`,
+or use `CommandPlanModel(CommandSpec(...))` directly.
+
+**Any other SDK or model** needs a class with a `propose` method, and a factory registered under
+the `flowglyph.planners` entry point group:
+
+<!-- planner-example -->
+```python
+from collections.abc import Sequence
+from typing import Any
+
+import my_sdk
+
+from flowglyph.planner import PlanModel
+from flowglyph.planner.model import Plan, plan_json_schema
+from flowglyph.planner.prompt import SYSTEM_PROMPT, request_text
+
+
+class MySdkPlanModel:
+    """Proposes plans through my_sdk."""
+
+    def __init__(self, model: str) -> None:
+        self.model = model
+
+    def propose(self, requirements: str, candidates: Sequence[dict[str, Any]]) -> Plan:
+        """Send the shared prompt and schema; parse the answer as a plan."""
+        answer = my_sdk.complete(
+            model=self.model,
+            system=SYSTEM_PROMPT,
+            prompt=request_text(requirements, candidates),
+            json_schema=plan_json_schema(),
+        )
+        return Plan.model_validate_json(answer)
+
+
+def my_sdk_planner(model: str | None, effort: str | None) -> PlanModel:
+    """Factory FlowGlyph calls with `--model` and `--effort`."""
+    return MySdkPlanModel(model or "my-default-model")
+```
+
+```toml
+[project.entry-points."flowglyph.planners"]
+my-sdk = "flowglyph_my_sdk:my_sdk_planner"
+```
+
+`flowglyph plan requirements.md catalog --via my-sdk` then uses it, and
+`FLOWGLYPH_PLANNER=my-sdk pytest -m llm` runs the planner evaluation against it. Use the shared
+`SYSTEM_PROMPT`, `request_text` and `plan_json_schema` so every backend is asked the same thing.
+Send nothing but the requirements and the candidate cards.
+
+## Commits and pull requests
+
+- Use [Conventional Commits](https://www.conventionalcommits.org/): `feat:`, `fix:`,
+  `docs:`, `refactor:`, `test:`, `chore:`.
+- Sign off every commit (`git commit -s`). This certifies the
+  [Developer Certificate of Origin](https://developercertificate.org/): that you wrote the
+  change or have the right to submit it under the project's license.
+- Add an entry under `Unreleased` in `CHANGELOG.md` for user-facing changes.
+- Keep pull requests focused. A refactor and a feature are two pull requests.
+
+## Reporting bugs and proposing features
+
+Use the issue templates. For security issues, follow [SECURITY.md](SECURITY.md) instead.
+
+By participating you agree to abide by the [Code of Conduct](CODE_OF_CONDUCT.md).