flo-pm 0.1.0__tar.gz

flo_pm-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.DS_Store
+__pycache__/
+*.pyc
+.venv/
+dist/
+*.egg-info/

flo_pm-0.1.0/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.5
+Name: flo-pm
+Version: 0.1.0
+Summary: Static sites and reports from a repo's .issues/ and .context/ markdown
+Project-URL: Repository, https://github.com/BramEsposito/flo-pm
+Project-URL: Issues, https://github.com/BramEsposito/flo-pm/issues
+Requires-Python: >=3.11
+Requires-Dist: markdown>=3.5
+Requires-Dist: pyyaml>=6.0
+Description-Content-Type: text/markdown
+
+# flo
+
+Static sites and reports from a repository's own markdown: an issue backlog
+in `.issues/`, the project's design context in `.context/`, and release
+reports read off both. No server and no database: the issue files live next
+to the code they are about, and every page works straight from `file://`.
+
+| Command | Builds | From |
+|---|---|---|
+| `flo issues` | a filterable issues site, one page per issue | `.issues/*.md`, `[labels]` |
+| `flo context` | a site of the project's scope files, checked for broken deep links | `.context/**/*.md` |
+| `flo burnup` | a burnup chart: scope against closed, per release | the issues |
+| `flo roadmap` | when each release can ship, theme by theme, at the planned pace | the issues + `[roadmap]` |
+| `flo workpackages` | the open work grouped into packages, and each one's progress | the issues + `[workpackages]` |
+| `flo epics` | every issue ever filed grouped by the part of the product it belongs to, with each epic's points left, pace and history | the issues + `[epics]` |
+| `flo delivery` | what stands between a release and shipping, with code checks | the issues + `[delivery]` |
+| `flo build` | all of the above that the project has inputs for | |
+| `flo init` | sets a project up for all of it | |
+| `flo migrate` | folds an older project's `labels.toml`, `roadmap.toml`, … into `flo.toml` | |
+
+`examples/kettle/` is a complete project to look at: a pickup-ordering app
+for a fictional bakery chain, with eighteen issues, a context directory and
+every report configured. `cd examples/kettle && flo build` and open
+`dist/issues-site/index.html`.
+
+## Install
+
+Globally, as a command available in every project:
+
+```sh
+uv tool install flo-pm                 # or: pipx install flo-pm
+```
+
+Or per project, pinned with the rest of the dev tooling:
+
+```sh
+uv add --dev flo-pm                    # then: uv run flo build
+```
+
+The package is `flo-pm` on PyPI (`flo` there is an unrelated project);
+either way the command is `flo`, and it reads the `flo.toml` of whatever
+project you run it in. Python 3.11+.
+
+## Start a project
+
+```sh
+flo init --name Kettle --prefix KET --reports
+flo build
+```
+
+`init` writes `flo.toml` — flo's settings and the `[labels]` every issue is
+checked against — an issues directory and a context directory, each with a
+README that explains its conventions, a `TEMPLATE.md` to copy and an icon, and
+a starter issue and scope file. `--reports` adds the `[roadmap]`,
+`[workpackages]` and `[delivery]` blocks. It only ever adds — files, and
+blocks to an existing `flo.toml` — so it is safe to run in a project that
+already has some of them.
+
+Both directories are [Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
+bundles as they stand: every markdown file `init` writes carries a `type`
+(`Issue`, `Context`, `Guide`), the one key OKF requires, and the sites warn
+about a file without one. `index.md` and `log.md`, the names OKF reserves,
+are never read as issues or scopes.
+
+The conventions are the substance: **one markdown file per issue, which never
+moves; `status` is the only thing that says where it stands; one context file
+per scope, split into AS IS and TO BE, with no history in it.** The two READMEs
+`init` writes spell them out, and the sites warn when a file breaks them.
+
+## `flo.toml`
+
+Everything flo needs to know about a project, in one file with one clearly
+marked block per concern: flo's own settings, then the project's data — the
+label vocabulary and the plans the reports are drawn from. Found by walking up
+from the working directory, so `flo` works from anywhere in the project. Paths
+are relative to the file.
+
+```toml
+# ══ flo — where things are, what issues are called, how the sites look ══════
+[project]
+name = "Kettle"          # shown on every page (default: the directory name)
+id_prefix = "KET"        # issues are KET-1, KET-2, … (default: ISS)
+
+[paths]
+issues = ".issues"
+context = ".context"
+out = "dist"             # each site is a directory under it
+
+[urls]                   # where a dev server serves each site, if one does
+issues = "/issues/"      # (defaults: /issues/, /context/, /burnup/, …)
+
+[theme]
+css = "flo-theme.css"    # inlined at the end of every page's <head>
+fonts = "https://fonts.googleapis.com/css2?family=…"
+
+[menu]                   # the strip of links across the pages, in order
+tools = ["issues", "context", "burnup", "roadmap", "workpackages", "epics", "delivery"]
+home = { label = "Home", url = "/" }
+
+# ══ labels — the vocabulary every issue is checked against ══════════════════
+[labels.issue]           # which frontmatter keys every issue must answer
+[labels.status]          # one section per label field, with its allowed values
+[labels.assignee]
+[labels.tags]            # … and any field of your own: version, points, theme
+
+# ══ roadmap — the plan `flo roadmap` lays the releases out by ═══════════════
+[roadmap.plan]           # start, pace, baseline
+[[roadmap.release]]      # each release, its reserve…
+[[roadmap.release.theme]]  # …and the themes it is scheduled in
+
+# ══ workpackages — what each package of work is ═════════════════════════════
+[workpackages]           # the releases in scope, the baseline
+[[workpackages.kind]]
+[[workpackages.package]]
+# ══ epics — what each epic is ════════════════════════════════════════════════
+[[epics.epic]]           # key, name, blurb; an issue's `epic` names one
+
+# ══ delivery — the recommended path the delivery report follows ═════════════
+[delivery.review]        # the review date and the release it was for
+[[delivery.lane]]        # the order to clear the work in
+```
+
+`examples/kettle/flo.toml` is a complete one, every block filled in. A project
+without a `[roadmap]` simply has no roadmap — `flo build` skips it — and the
+same goes for the other two report blocks.
+
+Older projects kept the data blocks as files of their own in the issues
+directory (`labels.toml`, `roadmap.toml`, `workpackages.toml`, `epics.toml`,
+`delivery-review.toml`). flo still reads those, with a note, and `flo migrate`
+folds them into `flo.toml` — comments and all — checking that each block reads
+back as its file did before deleting the file.
+
+Every command's flags default to these values, and still override them: `flo
+roadmap --as-of 2026-11-01`, `flo issues --watch`. `flo <command> --help`
+lists them.
+
+## Theming
+
+Every page ships flo's neutral theme — system fonts, a palette declared as
+custom properties on `:root`, redefined for dark mode. A project's `[theme]
+css` comes after it, so redefining a property wins. Define dark-mode values
+with the pages' own selectors (`@media (prefers-color-scheme: dark) {
+:root:not([data-theme="light"]) { … } }` and `:root[data-theme="dark"]`);
+they are more specific than a bare `:root`. `examples/kettle/flo-theme.css`
+covers the tokens each page reads.
+
+## Development
+
+```sh
+uv venv && uv pip install -e . pytest
+.venv/bin/python -m pytest
+```
+
+CI runs the tests on every push and pull request
+(`.github/workflows/ci.yml`). A version tag publishes to PyPI: bump `version`
+in `pyproject.toml`, commit, then `git tag v<version> && git push origin
+v<version>` (`.github/workflows/publish.yml`, through PyPI trusted
+publishing — no token is stored).
+
+The test suite builds the Kettle example and a freshly initialised project,
+and fails on any build warning — so a change to a generator, a template or the
+example is checked end to end.

flo_pm-0.1.0/README.md

@@ -0,0 +1,162 @@
+# flo
+
+Static sites and reports from a repository's own markdown: an issue backlog
+in `.issues/`, the project's design context in `.context/`, and release
+reports read off both. No server and no database: the issue files live next
+to the code they are about, and every page works straight from `file://`.
+
+| Command | Builds | From |
+|---|---|---|
+| `flo issues` | a filterable issues site, one page per issue | `.issues/*.md`, `[labels]` |
+| `flo context` | a site of the project's scope files, checked for broken deep links | `.context/**/*.md` |
+| `flo burnup` | a burnup chart: scope against closed, per release | the issues |
+| `flo roadmap` | when each release can ship, theme by theme, at the planned pace | the issues + `[roadmap]` |
+| `flo workpackages` | the open work grouped into packages, and each one's progress | the issues + `[workpackages]` |
+| `flo epics` | every issue ever filed grouped by the part of the product it belongs to, with each epic's points left, pace and history | the issues + `[epics]` |
+| `flo delivery` | what stands between a release and shipping, with code checks | the issues + `[delivery]` |
+| `flo build` | all of the above that the project has inputs for | |
+| `flo init` | sets a project up for all of it | |
+| `flo migrate` | folds an older project's `labels.toml`, `roadmap.toml`, … into `flo.toml` | |
+
+`examples/kettle/` is a complete project to look at: a pickup-ordering app
+for a fictional bakery chain, with eighteen issues, a context directory and
+every report configured. `cd examples/kettle && flo build` and open
+`dist/issues-site/index.html`.
+
+## Install
+
+Globally, as a command available in every project:
+
+```sh
+uv tool install flo-pm                 # or: pipx install flo-pm
+```
+
+Or per project, pinned with the rest of the dev tooling:
+
+```sh
+uv add --dev flo-pm                    # then: uv run flo build
+```
+
+The package is `flo-pm` on PyPI (`flo` there is an unrelated project);
+either way the command is `flo`, and it reads the `flo.toml` of whatever
+project you run it in. Python 3.11+.
+
+## Start a project
+
+```sh
+flo init --name Kettle --prefix KET --reports
+flo build
+```
+
+`init` writes `flo.toml` — flo's settings and the `[labels]` every issue is
+checked against — an issues directory and a context directory, each with a
+README that explains its conventions, a `TEMPLATE.md` to copy and an icon, and
+a starter issue and scope file. `--reports` adds the `[roadmap]`,
+`[workpackages]` and `[delivery]` blocks. It only ever adds — files, and
+blocks to an existing `flo.toml` — so it is safe to run in a project that
+already has some of them.
+
+Both directories are [Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
+bundles as they stand: every markdown file `init` writes carries a `type`
+(`Issue`, `Context`, `Guide`), the one key OKF requires, and the sites warn
+about a file without one. `index.md` and `log.md`, the names OKF reserves,
+are never read as issues or scopes.
+
+The conventions are the substance: **one markdown file per issue, which never
+moves; `status` is the only thing that says where it stands; one context file
+per scope, split into AS IS and TO BE, with no history in it.** The two READMEs
+`init` writes spell them out, and the sites warn when a file breaks them.
+
+## `flo.toml`
+
+Everything flo needs to know about a project, in one file with one clearly
+marked block per concern: flo's own settings, then the project's data — the
+label vocabulary and the plans the reports are drawn from. Found by walking up
+from the working directory, so `flo` works from anywhere in the project. Paths
+are relative to the file.
+
+```toml
+# ══ flo — where things are, what issues are called, how the sites look ══════
+[project]
+name = "Kettle"          # shown on every page (default: the directory name)
+id_prefix = "KET"        # issues are KET-1, KET-2, … (default: ISS)
+
+[paths]
+issues = ".issues"
+context = ".context"
+out = "dist"             # each site is a directory under it
+
+[urls]                   # where a dev server serves each site, if one does
+issues = "/issues/"      # (defaults: /issues/, /context/, /burnup/, …)
+
+[theme]
+css = "flo-theme.css"    # inlined at the end of every page's <head>
+fonts = "https://fonts.googleapis.com/css2?family=…"
+
+[menu]                   # the strip of links across the pages, in order
+tools = ["issues", "context", "burnup", "roadmap", "workpackages", "epics", "delivery"]
+home = { label = "Home", url = "/" }
+
+# ══ labels — the vocabulary every issue is checked against ══════════════════
+[labels.issue]           # which frontmatter keys every issue must answer
+[labels.status]          # one section per label field, with its allowed values
+[labels.assignee]
+[labels.tags]            # … and any field of your own: version, points, theme
+
+# ══ roadmap — the plan `flo roadmap` lays the releases out by ═══════════════
+[roadmap.plan]           # start, pace, baseline
+[[roadmap.release]]      # each release, its reserve…
+[[roadmap.release.theme]]  # …and the themes it is scheduled in
+
+# ══ workpackages — what each package of work is ═════════════════════════════
+[workpackages]           # the releases in scope, the baseline
+[[workpackages.kind]]
+[[workpackages.package]]
+# ══ epics — what each epic is ════════════════════════════════════════════════
+[[epics.epic]]           # key, name, blurb; an issue's `epic` names one
+
+# ══ delivery — the recommended path the delivery report follows ═════════════
+[delivery.review]        # the review date and the release it was for
+[[delivery.lane]]        # the order to clear the work in
+```
+
+`examples/kettle/flo.toml` is a complete one, every block filled in. A project
+without a `[roadmap]` simply has no roadmap — `flo build` skips it — and the
+same goes for the other two report blocks.
+
+Older projects kept the data blocks as files of their own in the issues
+directory (`labels.toml`, `roadmap.toml`, `workpackages.toml`, `epics.toml`,
+`delivery-review.toml`). flo still reads those, with a note, and `flo migrate`
+folds them into `flo.toml` — comments and all — checking that each block reads
+back as its file did before deleting the file.
+
+Every command's flags default to these values, and still override them: `flo
+roadmap --as-of 2026-11-01`, `flo issues --watch`. `flo <command> --help`
+lists them.
+
+## Theming
+
+Every page ships flo's neutral theme — system fonts, a palette declared as
+custom properties on `:root`, redefined for dark mode. A project's `[theme]
+css` comes after it, so redefining a property wins. Define dark-mode values
+with the pages' own selectors (`@media (prefers-color-scheme: dark) {
+:root:not([data-theme="light"]) { … } }` and `:root[data-theme="dark"]`);
+they are more specific than a bare `:root`. `examples/kettle/flo-theme.css`
+covers the tokens each page reads.
+
+## Development
+
+```sh
+uv venv && uv pip install -e . pytest
+.venv/bin/python -m pytest
+```
+
+CI runs the tests on every push and pull request
+(`.github/workflows/ci.yml`). A version tag publishes to PyPI: bump `version`
+in `pyproject.toml`, commit, then `git tag v<version> && git push origin
+v<version>` (`.github/workflows/publish.yml`, through PyPI trusted
+publishing — no token is stored).
+
+The test suite builds the Kettle example and a freshly initialised project,
+and fails on any build warning — so a change to a generator, a template or the
+example is checked end to end.

flo_pm-0.1.0/examples/kettle/.context/README.md

@@ -0,0 +1,184 @@
+---
+type: Guide
+title: Context conventions
+---
+
+# Context
+
+This directory records **Kettle's context**: standing, formalized facts,
+designs and decisions. `.issues/` tracks work that still needs doing;
+`.context/` tracks what the project *is* and what it is *meant to become*,
+so neither has to be reconstructed from scattered conversations every time
+it's relevant.
+
+Three rules govern everything below:
+
+1. **One file per scope.** Every scope gets a context file, and the
+   information for that scope is recorded **in that file only** — never
+   duplicated into a second file, an issue, or an agent's instructions file.
+2. **Every file splits into AS IS and TO BE.** What exists today, and what is
+   designed but not built yet.
+3. **No history.** Git log is the history.
+
+---
+
+## 1. One file per scope, referenced by deep link
+
+Each scope is written down **once**, in its own file. Anything elsewhere that
+needs that information — another context file, an issue, a README, a code
+comment, a commit message — **links to it instead of restating it**.
+
+- Link with a **deep link to the heading**, not just the file, so the reader
+  lands on the fact rather than on a 600-line document:
+  - from inside `.context/` — `[refunds](payments.md#refunds)`
+  - from anywhere else in the repo —
+    `[refunds](.context/payments.md#refunds)`
+- Anchors are the GitHub slug of the heading text: lowercased, spaces to `-`,
+  punctuation dropped (`### Refunds (v2, current)` → `#refunds-v2-current`).
+  Keep headings stable-ish; when you rename one, fix the links that pointed at
+  it (`grep -rn 'payments.md#old-anchor' --include='*.md' .`).
+- If you catch yourself re-explaining something that lives in another scope's
+  file: delete the explanation, link to it. A summarizing sentence plus a deep
+  link is fine; a second copy of the facts is not — two copies drift, and then
+  neither is trustworthy.
+- If a fact doesn't fit any existing scope, that's the signal to create a new
+  scope file, not to park it in the nearest one.
+
+## 2. AS IS and TO BE
+
+Every scope file has exactly these two top-level sections, in this order:
+
+```
+# <Scope title>
+
+  intro: what this file is the source of truth for
+
+## AS IS            ← the current design: what is built and running today
+  ### <sub-topic>
+  ### <sub-topic>
+
+## TO BE            ← the designed-but-not-yet-built target state
+  ### <sub-topic>
+  ### <sub-topic>
+
+## See also
+```
+
+- **AS IS** — the design as it actually exists in the code right now. Cite
+  code as evidence: `src/orders/checkout.py:120-180`, `Basket.total`.
+- **TO BE** — functionality that is *designed* but not built. Each entry says
+  what the target state is and links the issue that will build it
+  (`[[KET-40]]`). A TO BE entry with no issue behind it is a design
+  note, not a plan — say so (`**Issue:** none filed`).
+- Keep the boundary sharp. Never let a TO BE design read as if it were live,
+  and mark status explicitly per sub-topic: **decided** / **confirmed** /
+  **to be decided**. Something that's built but behind a debug flag is AS IS —
+  and says so.
+- When a TO BE item ships, **move it into AS IS and rewrite it in the present
+  tense**. Don't leave the old TO BE text behind as a record of what was
+  planned — that's history (rule 3).
+- Either section may be empty: write `_Nothing designed beyond AS IS._` or
+  `_Not built yet._` rather than dropping the heading, so its absence never
+  has to be interpreted.
+- **One exception: a catalog** — a file whose body is a list of like entries
+  (rules, an inventory of feature flags) may carry a **status per entry**
+  instead of the two blocks, since that is the same distinction at a finer
+  grain. It must say the word "catalog" in its first paragraph — that's how
+  the site recognises one — and every not-yet-implemented entry still links
+  its issue.
+
+### Formatting within a section
+
+Use the full toolbox — these files are read to answer a question fast, not
+front to back:
+
+- **Headings and subheadings** (`###`, `####`) per sub-topic — they're also
+  the deep-link targets other files point at.
+- **Bulleted lists** for facts, constraints and caveats.
+- **Numbered lists** for anything with an order: a flow, a sequence of steps,
+  a release procedure, ranked options.
+- **Tables** for inventories: settings keys, endpoints, environment variables.
+- **Diagrams** for anything with shape — a request flow, a state machine. ASCII
+  box drawings in a fenced block, or a fenced `mermaid` block; put the diagram
+  before the prose that explains it.
+
+## 3. No history
+
+These files describe the **current** state of the world, not how it got there.
+
+- **Don't** write changelogs, "previously we…", "Update: X removed", dated
+  decision logs, or "kept for anyone revisiting" option write-ups.
+- **Do** just state what is true now. When a fact changes, **overwrite** it
+  and bump `updated`.
+- To consult how a fact got to be the way it is, use git: `git log -p --
+  .context/<scope>.md`, or `git log -S '<phrase>' -- .context/`.
+- Two things that look like history and are not, so keep them:
+  - a *constraint* that happens to be dated — "the production schema is
+    deployed, so a stored field can't be renamed";
+  - **provenance** — "decided by Ada, 2026-09-25" against a rule or a
+    decision. That says who to ask whether it still holds, which is a present
+    fact about the rule, not a record of a change to it.
+
+A dated checklist or a session log is not a scope file; the work in one
+belongs in `.issues/`, and the narrative in git.
+
+## Where a scope file goes
+
+`.context/` is **flat** until it isn't: every scope file sits directly in
+this directory while there are a dozen of them, because a directory tree would
+only add places to look.
+
+When the directory grows a cluster of three or more scopes about one subject,
+group them in a subdirectory whose `README.md` is **the group's own scope
+file**: AS IS / TO BE for what is true of the group as a whole, plus an index
+of the children. Two files don't need a directory.
+
+The cross-cutting axis is `area` (see **Frontmatter fields**), not the
+directory — the site filters on it.
+
+## Filename
+
+`<scope>.md`, a short lowercase slug with `-`, one file per scope (e.g.
+`payments.md`, `store-hours.md`). No numbering — scopes aren't a sequence, so
+files are found and referenced by name.
+
+## Creating a new scope file
+
+Copy `TEMPLATE.md` to `<scope>.md` and fill it in.
+
+## This directory is also a site
+
+`flo context` renders this directory into a site and **checks the rules above
+while it does** — a deep link whose `#anchor` names no heading, a reference to
+a scope file or issue that doesn't exist, a missing `title`/`area`/`updated`, a
+file with neither section, a TO BE entry with no issue behind it. Those all
+render as perfectly ordinary pages, which is why they are worth a build
+warning, so read the output after editing.
+
+```sh
+flo context           # → the context site, under the output dir in flo.toml
+flo context --watch   # rebuild on every edit
+```
+
+## Frontmatter fields
+
+- **type** — `Context`, always: the [Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
+  concept kind, the one key OKF requires of every markdown file. With it this
+  directory is an OKF bundle as it stands; `index.md` and `log.md` are the
+  names OKF reserves, and the site never reads either as a scope
+- **title** — short scope title
+- **area** — one subsystem tag, from the same vocabulary as the `tags` in
+  `[labels.tags]` in `flo.toml`. Need a new one? Add it there first.
+- **updated** — date of the last real change (YYYY-MM-DD); bump it whenever a
+  fact or decision in the file changes, not on cosmetic edits
+
+## Cross-linking with `.issues/`
+
+- Every TO BE sub-topic links the issue that will build it, as
+  `[[KET-NN]]` or `` `.issues/KET-NN-slug.md` `` — the site
+  turns both into links.
+- Every issue that depends on a recorded fact deep-links into the AS IS
+  section holding it rather than restating it.
+- `.issues/` is authoritative for *status of work*; `.context/` is
+  authoritative for *design*. If they disagree about whether something is
+  built, the issue file wins and this directory is stale — fix it.

flo_pm-0.1.0/examples/kettle/.context/TEMPLATE.md

@@ -0,0 +1,45 @@
+---
+type: Context
+title: Short scope title
+area: 
+updated: YYYY-MM-DD
+---
+
+# <Scope title>
+
+One or two sentences: what this file is the source of truth for. Deep-link to
+other scope files instead of repeating what they already record
+(`[refunds](payments.md#refunds)`).
+
+## AS IS
+
+What is built and running today. Delete nothing into history — overwrite.
+
+### <Sub-topic>
+
+- **Status:** confirmed / decided
+- The fact itself, with evidence (`path/to/file.py:123`).
+
+### <Sub-topic with shape>
+
+```
+  A ──▶ B ──▶ C        diagram first, prose after
+```
+
+1. Ordered step
+2. Ordered step
+
+## TO BE
+
+Designed, not built yet. `_Not built yet._` if there's nothing.
+
+### <Sub-topic>
+
+- **Status:** decided / to be decided
+- **Issue:** `.issues/KET-XX`
+- The target state, in the future tense, and what it replaces in AS IS.
+
+## See also
+
+- `.issues/KET-XX` — related open work
+- Other scope files this one deep-links into

flo_pm-0.1.0/examples/kettle/.context/favicon.svg

@@ -0,0 +1,14 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16">
+ <!-- Stacked layers: one scope per file, and the directory is the stack.
+      Deliberately not the issues site's icon (three list rows) — the two
+      sites are read side by side, and a tab strip is where they are told
+      apart. Themed both ways: the browser's chrome follows the OS, not the
+      page, so a single fill would be invisible on one of the two. -->
+ <style>
+  path { fill: #15171a }
+  @media (prefers-color-scheme: dark) { path { fill: #e7e9ec } }
+ </style>
+ <path d="M8 1 15 4.3 8 7.6 1 4.3Z"/>
+ <path d="M1 7.7 8 11 15 7.7 13.2 6.8 8 9.3 2.8 6.8Z"/>
+ <path d="M1 11.1 8 14.4 15 11.1 13.2 10.2 8 12.7 2.8 10.2Z"/>
+</svg>

flo_pm-0.1.0/examples/kettle/.context/loyalty.md

@@ -0,0 +1,37 @@
+---
+type: Context
+title: Loyalty — points for regulars
+area: loyalty
+updated: 2026-09-29
+---
+
+# Loyalty
+
+The loyalty scheme Crumb & Co wants for v1.1: why regulars would order through
+Kettle rather than a marketplace.
+
+## AS IS
+
+_Not built yet._
+
+## TO BE
+
+### Earning and spending points
+
+- **Status:** to be decided
+- **Issue:** [[KET-12]]
+- One point per euro spent on a `paid` order, credited when the order is
+  `collected` (see [order states](ordering.md#order-states)).
+- 100 points buy a free coffee. Whether points expire is waiting on
+  Crumb & Co — decided by Sam once they answer.
+
+### Accounts
+
+- **Status:** decided
+- **Issue:** [[KET-13]]
+- Points need an account: email and a magic link, no passwords. An order
+  placed without an account earns nothing.
+
+## See also
+
+- [[KET-12]], [[KET-13]] — the v1.1 work

flo_pm-0.1.0/examples/kettle/.context/menu.md

@@ -0,0 +1,42 @@
+---
+type: Context
+title: Menu — products, allergens and prices
+area: menu
+updated: 2026-09-25
+---
+
+# Menu
+
+What Kettle sells, what is in it and what it costs. The menu is Crumb & Co's;
+Kettle only shows it.
+
+## AS IS
+
+### Products and allergens
+
+- **Status:** confirmed
+- A product belongs to one category and carries a list of the fourteen EU
+  allergens as data (`src/menu/models.py:10-52`), never as free text.
+- Every product page lists its allergens as text and as labelled icons.
+- Which shops sell a product is a list on the product: the station shops
+  carry a shorter menu.
+
+### Prices
+
+- **Status:** confirmed
+- One online price per product, the same in every shop.
+- An order keeps the prices it was placed at; a price change never touches an
+  order that already exists.
+
+## TO BE
+
+### Signed-off price list
+
+- **Status:** decided
+- **Issue:** [[KET-18]]
+- Online prices go live only once Crumb & Co has signed off the list. Some
+  products are 5% above the shop price, to cover the payment fees.
+
+## See also
+
+- [ordering](ordering.md#basket-and-checkout) — how prices are fixed on an order