# Context for AI agents contributing to this book

You are reading the machine-facing brief of the **PoliRural+ interactive policy
book** (p-book). Your human belongs to the PoliRural+ consortium and was invited
to co-create this knowledge base — you are welcome to help them, with their
context and under their name. Humans decide; agents draft.

## Why this book exists

Two goals, one artifact:

1. **The shared, public knowledge base of the PoliRural+ project** (EU Horizon Europe,
   GA 101136910, 20 partners, 9 pilot regions): pilots, Regional Action Plans, the
   multi-actor and foresight method, EU rural policy, the platform and GeoAI/JackDaw,
   food chains, innovation, open calls, results — kept alive by the consortium rather
   than frozen in deliverables.
2. **A proof of concept of a LOCAL GeoAI knowledge base** — chapter 4 seeds one for the
   Klatovsko district (Czechia): blocks grounded in open geodata (Copernicus, LPIS,
   cadastre, OSM, national statistics), readable by people and by AI agents, replicable
   by any pilot region (`content/ch04-geoai/08–10`, with Czech tellings `08b–10b`).

## Reading the book as an agent

- `/api/mcp` — read-only MCP server (Streamable HTTP, JSON): `search`, `get_concept`,
  `get_block`, `list_chapters`, `list_datasets`, `query_dataset`.
- `/kb` and `/kb/<concept>` — static pages with JSON-LD (cite these), `/llms.txt`,
  `/llms-full.txt`, `/kb/index.json`.
- `/content/book.json` (reading order), `/content/concepts.json` (concepts and their
  contracts — generated, never edit by hand), `/content/missions.json`, `/games/*.json`,
  open data under `/data/`.

## How content works

- A **block** = one markdown file in `content/chNN-*/` with **flat** YAML frontmatter
  (no nested maps; lists only as `highlights:` + `  - "item"`).
- A **concept** = one must-learn idea. Its **anchor** is the `NN-spine-*.md` file that
  carries `concept:` + `conceptTitle:` + the contract `recallQ` / `recallA` / `highlights`.
  Other tellings of the same idea (another region, Czech, shorter, deeper, a worked
  example) are satellites with the same `concept:` and a filename without `-spine-`.
- `type: spine | question | game`. Questions are one scenario with options A)–D) and
  `feedbackA…D`; games are data in `games/<slug>.json` + a `type: game` block
  (types `sort`, `pairs`, `order`, `pop`; every item has one answer an expert accepts and a `why`).
- **Facets** describe HOW a block tells, never WHAT: `lens` = the example world =
  **pilot region** (`generic · ireland · slovakia · greece · italy · finland ·
  czech-bavaria · spain · latvia · malta`), `lang` (`en · cs`), `depth`, `formalism`,
  `visuality`, `lengthBand`, `genre`. Decision tests: the engine brief in the p-book core
  (`recsys-pbook/AGENTS.md` §2) — with this book's lens vocabulary.
- Diagrams: `diagram: <id>` (ids in `js/diagrams.js`, files in `images/`); maps are
  generated by `scripts/build-maps.py` from Eurostat GISCO boundaries.

## The quality bar

- **Public sources only.** Every factual sentence traceable to a public, submitted or
  approved PU deliverable, the project website, CORDIS, the public Atlas
  (atlasbestpractices.com) or a named open dataset. Never: internal consortium registers,
  contact data, SEN deliverables, unpublished drafts, review comments, internal issues.
- End every block with `**Sources:**` — deliverable id, title, section, PDF URL.
  Never invent a number, URL, quote or status. A *proposed* hub is not *running*;
  a *Beta* is not *deployed*.
- Concrete over generic; 300–500 words per spine; one idea per block; `recallQ/recallA`
  is the contract — a reader must be able to answer it afterwards.
- Never change the `id` of an existing block (reader progress is keyed by it); retire
  blocks through `content/id-aliases.json` and `content/_archiv/`.

## How to contribute (APIs, no accounts)

Base URL: https://polirural-pbook.vercel.app — all endpoints are CORS-open.

- **Draft feedback loop**: `POST /api/drafts` `{action:'share', draft:{slug,title,text}, nick, group:'polirural'}`
  → `{id}`; humans comment at `/#zpetna-vazba-<id>`; gallery of the consortium:
  `/#trida-polirural`.
- **Slide decks** (SlAIdy bundles): `POST /api/decks` `{action:'save', group:'polirural', title, deck}`;
  `GET /api/decks?id=<id>` returns the raw bundle; `PUT /api/decks?id=<id>` saves a revision.
  Open in the editor: `https://kordikp.github.io/slaidy/?deck=<encoded GET url>`.
- **Reactions** (after a presentation): `POST /api/drafts`
  `{action:'react', id, group:'polirural', voter, score:1|2|3, tags:[], note}`.
- **In-book authoring** (for humans): every block has a ✍️ button → author studio; share
  with class code `polirural` → the work shows in the consortium gallery, gets votes, and
  editors lift the best into the served book. The author's name travels with the block.

## Maintaining the repo (agents working in git)

```bash
node scripts/migrate-facets.js            # regenerate content/concepts.json (idempotent)
node .github/scripts/validate-content.js  # must report 0 errors
node scripts/check-games.mjs              # game data: answer keys, coverage
node scripts/build-llms-index.js          # llms.txt concept index
node scripts/build-kb.js                  # static /kb pages, kb/index.json, llms-full.txt, sitemap.xml
python3 scripts/build-visual-map.py       # Map view data
node serve-local.js 8777                  # local server incl. /api/*
```

The engine (`js/app.js`, `js/ux.js`, `js/games.js`, `api/*`, `admin.html`, the scripts
above except `build-maps.py` / `build-visual-map.py`) comes from the p-book core via
`recsys-pbook/scripts/core-sync.sh` — change it there, not here. Book identity lives in
`js/config.js` and `pbook.json`.

## What we ask of you as an agent

- Ground every factual sentence in your human's context or a citable public source;
  when a number is uncertain, name the data source instead of guessing.
- Write in your human's voice and under their name; disclose AI assistance in the draft
  note if they wish.
- Prefer improving an existing block or adding a telling (another region, Czech) over a
  near-duplicate concept; check the gallery and the chapter first.
- Keep the frontmatter contract intact; never change `id` of existing blocks.