flyto-core

# flyto-core Agent Rules

- Do not store credentials, PATs, cookies, bearer tokens, or account passwords in recipe YAML, tests, logs, or generated artifacts.
- Recipe credentials must be runtime parameters only. Do not put real secrets in defaults, examples, manifests, screenshots, or committed smoke reports.
- Before changing module registration, browser automation, recipe execution, or recipe bundle behavior, use flyto-indexer impact/search to understand callers.
- After changing recipes or recipe bundles, run the focused recipe bundle tests and a flyto-core recipe smoke.
- Before finishing any code change, run the relevant verify/test/smoke checks and record any skipped gate.
- Changes to Python source, routes, parsers, environment readers, recipes, or workflows must regenerate `docs/reference/` and pass `python scripts/check_documentation.py`.
- Public copy must use Flyto2 and only the approved `@flyto2.com` mailbox aliases; run `python scripts/check_brand_identity.py`.
- Install contributor dependencies with `pip install -e '.[dev]'`; runtime integrations belong in explicit package extras.
- Keep `.flyto-index/`, run outputs, screenshots, and other generated artifacts out of commits.

The normal release closure is documented in `docs/TESTING.md`. At minimum run
the documentation and brand checks, audited-surface Ruff checks, the
non-browser/non-E2E suite, package build plus Twine validation, npm audit, and
strict full-scan Flyto2 Indexer verification.

## Flyto2 Project Memory Contract

Every Flyto2 repository must keep this project-memory scaffold current:

- `AGENTS.md`: agent operating rules, repo-specific constraints, verification commands.
- `CLAUDE.md`: Claude-facing handoff rules when this repo is edited outside Codex.
- `PROJECT.md`: product purpose, owned surfaces, users, and non-goals.
- `ARCHITECTURE.md`: module boundaries, runtime shape, data flow, and integration points.
- `STATE.md`: current status, known risks, release/deploy state, and last verification.
- `ROADMAP.md`: near-term, later, and explicitly out-of-scope work.
- `tasks.md`: actionable checklist with owners/status when known.
- `DECISIONS.md`: durable architectural/product decisions with dates and rationale.
- `CHANGELOG.md`: user-visible or operator-visible changes.
- `docs/README.md`: index for durable docs in this repo.
- `workflows/*.md`: repeatable agent workflows for idea capture, planning, implementation, bugfix, refactor, investigation, and wrap-up.
- `handoffs/_registry.md`: index of handoffs; new handoffs use `YYYY-MM-DD-topic.md`.

When changing behavior, public copy, deployment, security posture, or frontend UX, update the relevant memory files in the same change. Do not leave stale brand, email, module count, route, or deployment information behind.

## Flyto2 Frontend Quality Gate

Any frontend, website, dashboard, extension webview, app screen, or generated UI in this repository must avoid these eight failures:

1. Ignoring accessibility: every interactive control needs keyboard access, visible focus, semantic HTML or ARIA, sufficient contrast, and useful alt/labels.
2. Missing responsive design: verify mobile, tablet, and desktop; no clipped text, overflow, hidden primary actions, or broken navigation.
3. Weak visual hierarchy: users must immediately see page purpose, primary action, status, and next step.
4. Template-looking UI: reuse Flyto2 design tokens and local components, but tailor layout and copy to the actual product surface.
5. Useless elements: remove decorative or placeholder UI that does not help the workflow, trust, navigation, or comprehension.
6. Unclear hierarchy: controls, cards, tables, panels, and modals must have clear grouping, spacing, headings, and state.
7. Unintuitive navigation: current location, back/forward paths, and cross-links to docs/blog/product pages must be obvious.
8. Hard-to-understand content: copy must be concrete, scannable, current, and consistent with Flyto2 terminology.

Frontend verification must include the relevant automated checks plus manual or screenshot review for responsive layout, accessibility states, navigation clarity, loading/empty/error states, and content readability. Public pages must preserve SEO basics: canonical URL, sitemap coverage, metadata, structured data when relevant, and no broken internal or external links.

## Repo notes

Merged from `CLAUDE.md` so Codex and Claude read one set of rules.

Read `STATE.md`, `ARCHITECTURE.md`, `DECISIONS.md`, and the latest handoff
before changing workflow, module, recipe, or browser validation behavior.

- Treat recipes as executable product-loop contracts.
- Keep credentials as runtime inputs or environment values, never checked-in
  docs or fixtures.
- Prefer DOM extraction and JavaScript evaluation for browser assertions; use
  screenshots only for visual/layout verification.
- Run `bash scripts/lint-project-memory.sh` after editing project memory files.
- Run `python scripts/check_documentation.py` after changing Python source,
  API routes, CLI parsers, recipes, environment readers, or workflows.
- Run `python scripts/check_brand_identity.py` after changing public copy.
- Install contributor dependencies with `pip install -e '.[dev]'`; do not make
  provider SDKs implicit base dependencies when an explicit extra is suitable.