Documentos internos
Espelho de leitura. A frase de operação é: editar no registo /admin/docs, não neste repositório, porque a sincronização volta por esse canal.
README.md
# Documentos do repositório Estes ficheiros são a cópia local das instruções editoriais. - [repo-standards.md](repo-standards.md) - [style-guide.md](style-guide.md) - [authority-sources.md](authority-sources.md) - [anti-slop-signatures.md](anti-slop-signatures.md) - [architecture.md](architecture.md) - [authors/hw-costa.md](authors/hw-costa.md) - [authors/loc-rodrigues.md](authors/loc-rodrigues.md) These docs are mirrored from the CMO admin /admin/docs registry. Edit there, not here — changes flow back via the doc-sync agent.
anti-slop-signatures.md
# Anti-slop signatures
Reject a page when the first 200 words contain any of these openings:
```
^(?:In today'?s|In a world where|Have you ever wondered|When it comes to|Welcome to the world of|It is important to note|It goes without saying|In the dynamic landscape of)
```
Also reject:
* "In today's world…", "In a world where…", "Have you ever…",
"When it comes to…", "Welcome to the world of…".
* The H1 keyword repeated 4 or more times in the first 200 words.
* No concrete number, date, or name in the first screen.
* Wikipedia or Investopedia treated as a Tier-1 source.
* Synonymous bullet lists ("It is easy", "It is simple", "It is straightforward").
* No outbound links, or only links to the same domain, on an article that had permitted external URLs.
* FAQ answers shorter than the questions.
* A closing paragraph that restates the introduction.
* Portuguese fillers of the same family: "No mundo de hoje", "Num mundo em que", "Quando se trata de", "É importante notar", "Não é preciso dizer".
Two or more of these patterns on one page fail the audit.
architecture.md
# Arquitetura de rotas Língua: pt-PT. Cidade única: Lisboa. Ofício único: instalação de ar condicionado. ## Rotas de contrato * `/` — tabela ordenada das fichas. * `/tools/` e `/tools/calculadora-carga-termica/` — calculadora. * `/resources/` e `/resources/calculadora-carga-termica/` — o mesmo texto, convenção editorial do perfil. * `/pillars/` e `/pillars/melhores-instalacao-de-ar-condicionado-em-lisboa/` — pilar. * `/pillars/melhores-instalacao-de-ar-condicionado-em-lisboa/<slug>/` — artigo. * `/guides/` e `/guides/<slug>/` — os mesmos artigos, ligações internas preferidas. * `/<slug>/` — ficha de uma empresa, só com os campos do JSON. * `/about/`, `/methodology/`, `/editorial-policy/`, `/corrections/`, `/contact/`. * `/authors/pedro-costa/` e `/authors/tiago-rodrigues/`. * `/list-your-business/` — explica um espaço pago futuro. Não rende linha patrocinada. * `/llms.txt`, `/llms-full.txt`, `/sitemap.xml`, `/robots.txt`. * `/admin/docs/` — espelho de leitura dos markdown em `docs/`. Não existe `/countries/`. O brief pediu zero hubs de país. ## JSON-LD * Todas as páginas: Organization + WebSite com SearchAction. * Artigos: Article + FAQPage + BreadcrumbList. Sem Product. * Ferramenta: SoftwareApplication + FAQPage + BreadcrumbList + Dataset com licença CC BY 4.0. * Ficha de empresa: Article + BreadcrumbList. Sem Product, sem review inventada, sem aggregateRating. * Autor: Person sem sameAs. ## Sitemap `siteUrl` vem de `SITE_URL` ou `NEXT_PUBLIC_SITE_URL` ou `https://` + `VERCEL_PROJECT_PRODUCTION_URL`. Não se grava um host `vercel.app` derivado do nome do repositório.
authority-sources.md
# Fontes autorizadas neste sítio O pacote de lançamento listou as fontes de autoridade como `(none)`. Não há, neste repositório, uma lista de 50 a 80 URLs de regulador, norma ou imprensa especializada fornecida pelo operador. Regra em vigor até o registo `/admin/docs` trazer URLs novas: * Não inventar citações a diplomas, portarias, normas ISO, manuais de fabricante ou artigos de imprensa. * Um facto numérico que não esteja no JSON das fichas, nem numa frase fechada deste brief, fica por escrever ou é marcado como não verificado. * Os únicos URL externos permitidos nas páginas de lançamento são os sítios `https://` que já vinham no campo `website` das fichas. ## Sítios https presentes nas fichas (acesso 9 nov 2026) | Ficha | URL | Tier nesta edição | | --- | --- | --- | | Assisglobo - Ar Condicionado | https://www.xn--assisgloboservios-osb.com/ | ficha (não é regulador) | | Inova | https://inovaarcondicionado.pt/site%3Futm_source%3Dgoogle_org%26utm_medium%3Dgooglemeunegocio | ficha (não é regulador) | | Master Reparações | https://snow-cobra-648331.hostingersite.com/ | ficha (não é regulador) | | Megaclima | https://www.megaclima.pt/ | ficha (não é regulador) | | AirTouch | https://airtouch.pt/ | ficha (não é regulador) | | Climatar Lisboa | https://climatar.pt/ | ficha (não é regulador) | | Sena & Leão Refrigeração | https://senaeleaorefrigeracao.netlify.app/ | ficha (não é regulador) | Os campos `website` em `http://` (Esavesat, Termo Clima, Nipolândia, ARL) são impressos como texto. Não entram como `<a href>` enquanto a regra de ligação externa exigir `https://`. ## O que não é fonte * Wikipedia, listicles e sítios de respostas geradas. * Uma nota Google que não esteja no JSON. * Um preço, um teste no local, um bairro ou uma morada que a ficha não traz.
authors/hw-costa.md
# Pedro Costa * id: hw-costa * slug: pedro-costa * name: Pedro Costa * title: Massagista terapêutico * locale: pt * bio: Massagista certificado em Sintra com formação em recuperação para ciclistas e corredores. Assina todas as páginas deste sítio. Não é instalador de AVAC. A revisão técnica das páginas de ofício cabe a Tiago Rodrigues.
authors/loc-rodrigues.md
# Tiago Rodrigues * id: loc-rodrigues * slug: tiago-rodrigues * name: Tiago Rodrigues * title: Consultor de instalações AVAC * locale: pt * bio: Quinze anos a instalar climatização em apartamentos de Lisboa e Porto. Escreve guias para clientes e instaladores. Revisor técnico. Não assina no lugar de Pedro Costa. A linha de revisão indica o nome dele e liga a `/authors/tiago-rodrigues/`.
repo-standards.md
# Design system — editorial, restrained, fast
The visual language must signal "editorial / research-grade" — not
"marketing landing page" and not "generic blog".
## Palette
* Pick ONE of two modes: editorial paper (warm off-white background) or
clean dark. Do not mix.
* **Three core colours max**, including the accent. The accent is the
niche's natural colour (finance → deep teal; health → sage; tax →
ochre; tech → indigo). Do not use neon/saturated CTAs.
* Background, surface, surface-2, border (hairline 1px), ink (primary
text), muted-ink (secondary text) — that is the entire neutral scale.
* Dark mode: persistent toggle in the header + `prefers-color-scheme`
on first paint.
## Typography
* H1/H2 — serif (Fraunces or Source Serif 4). H3 may stay serif or
switch to sans for hierarchy.
* Body + UI — Inter (or system-ui fallback).
* Maximum body width ~ 70ch on desktop. Articles use a 2-column shell
on ≥ 1200px: 70ch content + 280px sticky TOC sidebar.
* Numbers: tabular-figures (`font-variant-numeric: tabular-nums`) on
every table cell.
## Components — required catalogue
The seed agent must scaffold these in `/components/editorial/`:
* `<Callout intent="note|warn|insight">` — coloured-tint card with
hairline border. Used for "Editor's note" mid-article.
* `<StatCallout value="42%" source="…" />` — large stat with cited
source. Shareable as a screenshot.
* `<ProsCons />` — two-column dl with check / cross marks.
* `<PullQuote source="…" url="…">` — `<blockquote>` with cite attribute.
* A decision is a real `<table>`. Do not scaffold an inline SVG flowchart.
* `<ComparisonTable />` — real `<table>` with sticky header on mobile.
* `<Reference n={1} />` — superscript anchor link to the `<section
id="references">` at page bottom (Wikipedia-style numbered cites).
* `<Sidebar definitions />` + `<dfn>` for jargon, mirrored in glossary.
* `<WorkedExample name="Sarah, …">` — named-scenario block.
* `<CitationWidget />` — "How to cite this page" with APA / MLA /
Chicago snippets.
## Print stylesheet
* Articles must print cleanly on A4 / Letter. Header, footer, sidebars
hidden. Outbound links rendered as `[1] https://…` in footnotes.
## Accessibility
* Skip-to-content link as first focusable element.
* Visible focus-ring on every interactive element (`:focus-visible`).
* All images have `alt`. Decorative `alt=""` only when truly decorative.
* Contrast ≥ 4.5:1 for body, ≥ 3:1 for large text.
* Decision flowcharts and stat callouts have a text fallback for
screen readers.
## Performance
* AVIF + WebP fallback for every image (next/image handles both).
* Critical CSS extracted above-the-fold (`@layer base` discipline).
* `dns-prefetch` + `preconnect` for fonts.googleapis.com.
* PWA-lite: a tiny `service-worker.js` that caches `/`, `/llms.txt`,
and the last-visited article for offline reading.
---
# Authority sources — tiers, density, format
This is the E-E-A-T core. Every article cites **at least four** outbound
links from **at least two different tiers**, distributed through the
body — never lumped at the end.
## Source tiers
### Tier 1 — primary authority (must cite at least once per article)
Government bodies, regulators, statistical agencies, peer-reviewed
academic publications, official standards bodies, court rulings.
Examples by domain (extend per niche in the per-site
`docs/authority-sources.md`):
* **Finance / tax (US)** — IRS.gov, SEC.gov, FINRA.org, GAO.gov,
CFPB.gov, FederalReserve.gov, Treasury.gov.
* **Finance / tax (EU)** — ec.europa.eu, eba.europa.eu, esma.europa.eu,
ecb.europa.eu, national tax authorities (HMRC, DGFIP, AT, …).
* **Health** — WHO.int, CDC.gov, NIH.gov, EMA.europa.eu, NICE.org.uk,
Cochrane.org, NEJM.org, JAMA, Lancet.
* **Energy / solar** — IEA.org, IRENA.org, NREL.gov, eur-lex.europa.eu,
national energy regulators (ERSE/PT, CRE/FR, Ofgem/UK).
* **Technology / standards** — IETF.org RFCs, W3C, ISO, IEEE, NIST.gov.
### Tier 2 — specialised press + vendor docs (rotate; max 2 per article)
Niche trade publications, vendor changelogs / docs, well-known explainer
sites that publish primary reporting.
* Finance — Bloomberg, FT, Reuters, WSJ, Tax Foundation, Tax Policy
Center, Morningstar, Bogleheads.
* Tech — A16Z, Stratechery, official engineering blogs.
* Energy — PV Magazine, Solar Power World, government grant portals.
* SaaS / software — vendor changelog (`status.X.com`, release notes),
GitHub release pages, official API docs.
### Tier 3 — community + UGC (allowed, never primary)
Reddit threads, Stack Exchange, well-moderated forums, GitHub
discussions. Use to surface real-user pain — link only when the thread
contains primary information (e.g. a vendor employee responding) or a
broad-consensus answer with > 50 upvotes.
### Forbidden as primary
* Wikipedia (acceptable as a *fallback* link in a "for further reading"
context, never as evidence for a claim).
* Investopedia, About.com, generic "Top 10" listicles.
* AI-generated answer sites (`*.ai/answers/*`, etc.).
* Affiliate-only comparison sites (NerdWallet OK, "BestVPN2026" no).
## Density + distribution
* Minimum 4 outbound links per article, max ~10.
* At least one outbound link **above the fold** (inside the first
500 words) — usually anchored to the Tier 1 source for the headline
claim.
* Spread cites across sections. A reference-dump at the end is a slop
signal.
* Anchor text describes the cited document, not "click here" or "this
source". `rel="external"` (not `nofollow`) — we want Google to see we
trust real authority.
## Numbered references format
Use Wikipedia-style superscripts in the body and a `References` section
at the bottom.
```tsx
<p>
The IRS treats RSUs as supplemental wages on vest
<Reference n={1} />.
</p>
<section id="references">
<h2>References</h2>
<ol>
<li id="ref-1">
Internal Revenue Service. "Publication 525 — Taxable and
Nontaxable Income." 2025 ed., 14 Jan 2026. Accessed 12 Mar 2026.
<a href="https://www.irs.gov/forms-pubs/about-publication-525"
rel="external">irs.gov</a>.
</li>
…
</ol>
</section>
```
Each reference includes: author / publisher, title in quotes,
publication date, **access date**, hyperlink. Pull quotes use
`<blockquote cite="https://…">` with the source attribute.
## Anti-recycling
* Maximum **2 articles per site** citing the same Tier-2 URL. If you
need a third, find a different source.
* Across the network: the audit cron flags any URL cited on > 8 sites
and asks the operator to diversify.
## Per-site curation
A `docs/authority-sources.md` is committed in every repo at seed time.
It contains the niche-specific shortlist (50–80 entries) tagged with
tier. Articles should cite from this list first, fall back to general
Tier 1 when needed.
---
# Editorial style guide
Per-site style guide — committed in every repo as `docs/style-guide.md`.
The seed agent must read and apply this whenever it (or a future article
agent) writes content for the repo.
## Voice
* **Person:** First-person plural ("we") for the editorial team;
first-person singular ("I") in author-bylined opinion sections.
Never second-person ("you") for evidence claims; allowed in
instructional steps.
* **Tense:** Present for current facts, past for events, conditional
for hypothetical scenarios. Avoid "will" futurism unless backed by a
stated source / forecast.
* **Tone:** Confident but not breathless. Hedge thin evidence. Don't
oversell. No exclamation marks outside of pull quotes.
## Word choice
* Prefer concrete nouns ("the IRS rule", "the SEC 2025 update") over
abstractions ("the regulatory landscape").
* Replace "leverage" with "use", "utilise" with "use", "in order to"
with "to", "due to the fact that" with "because".
* No "very", "really", "quite", "actually", "literally" as
intensifiers.
* No corporate phrases: "best-in-class", "cutting-edge", "world-class",
"next-generation", "seamlessly", "robust solution".
## Numbers + units
* Spell out one-to-nine when narrative; numerals from 10 up.
* Currency with explicit currency code on first mention ("$80 USD",
then "$80"). Always state the date of any price.
* Percentages with one decimal max ("42.3%"), unless the source is
whole-number.
* Use the thin-space thousands separator (or comma per locale).
## Headings
* H1 — keyword-targeted, ≤ 60 chars.
* H2 — full sentences or question form ("How does the SEC's Rule 144
apply to RSUs?"). Avoid one-word H2s ("Pricing", "Features") —
too SEO-flat.
* H3 — used only when a H2 has ≥ 3 sub-points.
* No emoji in headings.
## Citations
* Outbound link with `rel="external"` (not `nofollow`). Anchor text
describes the cited document — never "click here".
* Pair every outbound link with an inline access date for primary
sources: "*IRS Publication 525, accessed 12 Mar 2026*".
## Internal linking
* 4–6 internal links per article minimum.
* Use the article's own H2 / H3 anchors when linking within a long
guide.
* Don't link the same internal URL twice in the same article.
## Tables
* Real `<table>` with `<thead>` and `<tbody>`.
* First column is the comparable axis (product / option / country).
* Numeric columns use tabular-figures CSS.
* A `<caption>` summarises the table and cites the source(s).
## Quotes
* Use `<blockquote cite="…">` with attribution.
* Maximum 50 words per quote — paraphrase the rest.
style-guide.md
# Editorial style guide
Per-site style guide — committed in every repo as `docs/style-guide.md`.
The seed agent must read and apply this whenever it (or a future article
agent) writes content for the repo.
## Voice
* **Person:** First-person plural ("we") for the editorial team;
first-person singular ("I") in author-bylined opinion sections.
Never second-person ("you") for evidence claims; allowed in
instructional steps.
* **Tense:** Present for current facts, past for events, conditional
for hypothetical scenarios. Avoid "will" futurism unless backed by a
stated source / forecast.
* **Tone:** Confident but not breathless. Hedge thin evidence. Don't
oversell. No exclamation marks outside of pull quotes.
## Word choice
* Prefer concrete nouns ("the IRS rule", "the SEC 2025 update") over
abstractions ("the regulatory landscape").
* Replace "leverage" with "use", "utilise" with "use", "in order to"
with "to", "due to the fact that" with "because".
* No "very", "really", "quite", "actually", "literally" as
intensifiers.
* No corporate phrases: "best-in-class", "cutting-edge", "world-class",
"next-generation", "seamlessly", "robust solution".
## Numbers + units
* Spell out one-to-nine when narrative; numerals from 10 up.
* Currency with explicit currency code on first mention ("$80 USD",
then "$80"). Always state the date of any price.
* Percentages with one decimal max ("42.3%"), unless the source is
whole-number.
* Use the thin-space thousands separator (or comma per locale).
## Headings
* H1 — keyword-targeted, ≤ 60 chars.
* H2 — full sentences or question form ("How does the SEC's Rule 144
apply to RSUs?"). Avoid one-word H2s ("Pricing", "Features") —
too SEO-flat.
* H3 — used only when a H2 has ≥ 3 sub-points.
* No emoji in headings.
## Citations
* Outbound link with `rel="external"` (not `nofollow`). Anchor text
describes the cited document — never "click here".
* Pair every outbound link with an inline access date for primary
sources: "*IRS Publication 525, accessed 12 Mar 2026*".
## Internal linking
* 4–6 internal links per article minimum.
* Use the article's own H2 / H3 anchors when linking within a long
guide.
* Don't link the same internal URL twice in the same article.
## Tables
* Real `<table>` with `<thead>` and `<tbody>`.
* First column is the comparable axis (product / option / country).
* Numeric columns use tabular-figures CSS.
* A `<caption>` summarises the table and cites the source(s).
## Quotes
* Use `<blockquote cite="…">` with attribution.
* Maximum 50 words per quote — paraphrase the rest.
## Site-specific voice (fingerprint 39cc3d273f27)
The published pages of this site use European Portuguese (pt-PT) and a
conversational address. Instructional steps may use "tu". Evidence
claims stay tied to a field in the listing JSON or to a sentence that
this launch was told to print unchanged. Pedro Costa signs the pages.
Tiago Rodrigues is the technical reviewer.