Agents d'IA ↔ VISC

VISC (Vida, Informació, Serveis, Comunitat) is a multi-tenant platform where local communities — associations, neighbourhoods, cooperatives, local businesses — and the people around them organise daily life: agenda, news, payments, inscriptions, maps, tips and local commerce. It is rooted in Catalunya: all 947 municipalities are first-class pages, and the platform's content language is Catalan.

This document set exists so AI agents can understand VISC quickly and help its users well. Start here, then read the other docs listed in llms.txt.

The tenancy model

Three kinds of "place" organise everything on VISC:

• Localities — the 947 Catalan municipalities, plus their comarques (43), vegueries and provinces. Every locality has a public page at its slug (for example https://visc.cat/vic), with agenda, news, weather, natural spaces, webcams and citizen-curated topic pages. Localities are static reference data, not user content.
• Communities — tenant spaces created by real-world entities (an association, a neighbourhood, a cooperative, a shop, a sports club…). A community lives at https://visc.cat/{communitySlug} and owns its members, events, payments, products, threads and other records. Community content is private by default; only content explicitly promoted by the community appears on public territorial pages.
• The personal space — each signed-in person has a private dashboard (at /on on visc.cat) aggregating their feed, agenda, wallet (moneder), inscriptions, orders and communities across all tenants.

Public URL structure

Anything under /on/, /auth/, /org/ or /{slug}/admin is private and not crawlable.

Vocabulary

Catalan terms you will meet across the platform, kept untranslated on purpose:

• comarca / vegueria — Catalan territorial divisions between municipality and province.
• tema (topic) — a citizen-curated dossier page about a local matter, made of votable entries.
• moneder — a user's or community's wallet.
• vincle — a person↔person or person↔place bond (favourite, lived, visited…).
• fita — a milestone in the honest-gamification system (verifiable, no dark patterns).
• espai natural — a protected natural space (parks, wetlands, peaks).
• inscripció — a signup to a community event or course.
• iniciativa ciutadana — a civic initiative or petition, organised and signed on-platform.

What an agent can do today

There is no public API yet. What works today:

1. Read the public pages and these docs. Locality, comarca, community-showcase and topic pages are server-rendered and readable without authentication.
2. Author content for a user to paste. VISC forms accept structured markdown in bulk: one well-written string becomes a full topic page with dozens of entries. The exact contract is in authoring.md, worked examples in examples.md. This is deterministic parsing — no AI on the platform side — so the quality of the result is entirely in the string you write.

Content pasted into VISC must be in Catalan and grounded in real, verifiable sources — see the grounding rules in the authoring contract.

API and MCP roadmap

• Read API (planned): public, cache-friendly JSON for localities, agendas and promoted community content — the same data the public pages render.
• MCP server (planned): a Model Context Protocol server exposing safe read tools and, later, user-authorised write flows (draft a topic, prepare an inscription) with the user always in the loop.
• Today: nothing beyond the public pages and these docs is exposed. Endpoints described elsewhere are not real; do not invent them.

Interest or feedback: use the Envia feedback button in the footer of any VISC page — it reaches the platform team directly.

How to write one markdown string that a VISC user pastes into a creation form to get a rich, fully-populated page. Today this works for locality topics (citizen dossier pages); future importers (agenda programs, directories, FAQs) will reuse the same contract.

The loop: you compose ONE markdown string following this contract → the user opens the creation form (for topics: their locality page → Comença un tema) → pastes it into the Descripció field → reviews the detected sections and items in a preview panel → submits. Parsing is deterministic — the same string always produces the same page, no AI on the platform side — so the quality of the result is entirely in the string you write.

The contract — what each construct becomes

Rich content inside an entry

Standard markdown works inside one entry: [text](https://…) links and bare URLs (each URL on its own line also gets a link preview card — one fetch per URL, so use real, reachable links), YouTube URLs become a playable embed,  images (https only — a paste cannot upload files), GFM tables, > quotes, ``` `mermaid `` diagrams, bold, italics, strikethrough, code . 900 818 482 dials on tap and address` opens the mail client — neither href may contain spaces.

Controlling the layout

Entries render as cards in a masonry grid; each card's width is derived from its heft. Use it deliberately:

• Small (quarter width): entry under 200 chars — bare links, one-liners.
• Large (full width): entry of 900+ chars, or containing a table or an image.
• Medium (half width): everything else.

A good-looking page mixes them: a few Large anchor entries (the key report, a table, a photo), Medium analysis entries, Small link/fact entries.

Limits

Grounding rules

• Language: Catalan, always. The platform's content language. Write the whole paste in Catalan even though these docs are in English.
• Ground every fact in real sources; never invent. Use real press and official URLs only — a fabricated URL becomes a visibly dead link card that discredits the whole page.
• Don't put official file/reference numbers inside entries — tracked references are a separate feature the user adds on the page itself.
• One provenance per paste. All entries of one paste share one source chip (Official / Premsa / Ciutadania / Document). If the content mixes provenances, keep the paste to the main batch and let the user add the odd entries by hand.
• Make each entry self-contained. Entries are re-ranked by votes, so never encode meaning in their order — that's also why the section title is repeated inside each entry.

Template

# Abocador de Coll Cardús i les olors

El CTR tracta residus de tota la comarca i les queixes per pudor
s'acumulen des de 2019. Aquesta pàgina aplega documents oficials,
premsa i aportacions veïnals per seguir el cas.

## Documents oficials

- **Resolució de l'ARC (2023)** — obre expedient de control d'olors.
  https://arc.gencat.cat/exemple-resolucio
- **Informe municipal d'olors** amb els mesuraments de 2022 i 2023.
- Taula de llindars aprovats (la taula fa l'entrada d'amplada completa):

  | Paràmetre | Llindar |
  | --- | --- |
  | Unitats d'olor | 5 ouE/m³ |

## Cronologia

Els fets principals, dels més antics als més recents.

- **2019** — primeres queixes veïnals registrades a l'Ajuntament.
- **2021** — moció aprovada al ple per exigir mesures correctores.
- **2023** — l'ARC obre expedient i imposa mesures.

## Premsa

- Reportatge comarcal sobre l'onada de queixes.
  https://exemple-mitja.cat/reportatge
- https://www.youtube.com/watch?v=exemple

Three concrete ways an agent works with VISC today. The contract behind example 1 is in authoring.md — read it first.

Example 1 — generate a locality dossier

A user asks their assistant: "Prepara un tema sobre la festa major per al poble de Taradell."

The agent's loop:

1. Fetch https://visc.cat/llms.txt, read authoring.md.
2. Research real sources (the town's official program, local press).
3. Compose ONE Catalan markdown string following the contract. For a festa major program:

# Festa Major de Taradell 2026

Tot el programa de la festa major en una sola pàgina: actes,
horaris i enllaços oficials, per votar i comentar els actes.

## Divendres 14 d'agost

- **19.00 — Pregó d'inici** a la plaça de les Eres, a càrrec
  de la colla gegantera.
- **22.30 — Concert jove** al parc de Can Costa.
  https://exemple-ajuntament.cat/programa

## Dissabte 15 d'agost

- **11.00 — Cercavila de gegants** pel centre del poble.
- **18.00 — Ballada de sardanes** amb la cobla local.
- **23.00 — Ball de nit** al pavelló.

## Enllaços oficials

- Programa complet en PDF a la web municipal.
  https://exemple-ajuntament.cat/festa-major
- https://www.youtube.com/watch?v=exemple-aftermovie

1. The user pastes this into the Descripció field at their locality's Comença un tema form. The preview panel shows 3 sections and 7 entries; they pick the source type (here: Official) and submit.
2. Result: a topic page where each act is its own votable card. The one-line entries render Small, the entries with a URL get a link-preview card and render Medium, and the YouTube link renders as a playable embed.

What made this work: real URLs, Catalan, one provenance, self-contained entries (each act repeats enough context to stand alone once votes re-order them).

Example 2 — answer questions about a town

A user asks: "Què passa aquest cap de setmana a Ripoll?" — no VISC account needed. The public, server-rendered pages an agent can read:

• https://visc.cat/{localitySlug} — the municipality page: agenda, news, weather, topics.
• https://visc.cat/{comarcaSlug} — comarca-level agenda and news.
• https://visc.cat/catalunya — country-level explore page.

What an agent cannot do: read community-internal content (member events, payments, threads), act on behalf of a user, or call any API — none exists yet. When the platform's read API and MCP server land (see the roadmap in overview.md), this section will be replaced by tool documentation.

Example 3 — a prompt VISC users can copy

Users who want their own assistant to prepare VISC content can hand it this prompt:

Read https://visc.cat/agents/authoring.md and follow its contract
exactly. Then write, in Catalan, a complete topic paste about
[SUBJECT] for the municipality of [TOWN]. Ground every fact in
real, reachable URLs (official sources and local press only) and
aim for 3-5 sections with 10-25 self-contained entries, mixing
entry sizes as the contract describes. Return only the markdown
string, ready to paste.

Replace [SUBJECT] and [TOWN], review what comes back — especially that every URL is real — and paste it into the topic form.