Working on pt.newsroom.sgit.ai: start here

Guidance · 1 of 6

Working on pt.newsroom.sgit.ai: start here

The first page to read before changing anything in this repository — human or agent. It is short on purpose and made mostly of edges: the rules that get broken most, and a route to the file that actually answers each question. If you are an agent and you fetch one thing, fetch llms.txt, which is this page in the form you prefer.

The one-minute version

Everything except what a visitor reads is in English. Pick your side of that line before you write a word — it decides your file names, your comments, your commit message and your JSON keys. Every claim walks back to bytes, and a claim with no frozen source is a build failure, not a warning. A rule without a gate is decoration — if you add a rule here, add the gate in the same change. Run python3 build/tudo.py before every commit: the order of its steps is load-bearing and running them by hand silently produces a smaller site — and python3 build/before_push.py before you take a version number, because two other sessions are working while you are. Only the named human editor publishes. Nothing you do may set estado: publicado.

Read in this order

	Read	Because
1	`language.md`	The rule that decides every naming question in this repository, and the one most likely to be got wrong
2	`principles.md`	The nine principles, each with the gate that enforces it. A principle with no gate is named as such
3	`../../CLAUDE.md`	The seven rules. It is the constitution; it outranks everything here, including this page
4	`before-you-change.md`	The checklist. What to read, what to run, what to record, in order
5	`concurrent-sessions.md`	Three sessions work here at once. What collides, what is gated, and the order that avoids most of it
6	`releasing.md`	Which component is the minor, the packages the build needs, the browser gate, and the merge commands that delete work silently
6	`../../agents/README.md`	Who you are. Every agent working here claims a named identity with a `ROLE.md` and a `MANDATE.md`
7	`../../briefs/pack/01__the-brief.md`	What this publication is for. Read it once; it is the reason the gates are shaped this way

Then, only when the task needs them: the estate's own guidance at sgit.ai/docs/guidance, the house style at coding.sgit.ai, and the non-functional requirements at nfrs.sgit.ai. This repository is an instance of that argument, not a restatement of it: where they answer a question, we link rather than copy.

What not to build

Most tasks end here.

A second way to read a document. <pt-doc-browser> is the one document reader. There was a second one for two releases and deleting it was a release of its own.
A second way to render a page. Nobody hand-edits a generated .html; the next build overwrites it and the edit is gone. Edit the builder.
A new gate file. New gates go in build/gates_artigos.py. build/gates.py is in the deny list of .claude/settings.json on purpose: an agent that can edit the gate that stops it has no gate at all.
A fix to CLAUDE.md so the code passes. That is backwards, and CLAUDE.md is deny-listed to make it awkward. If the rules and the code disagree, write to the editor's inbox (redacao/correio/editor/entrada/) and stop.
Comments, decisions or agent opinions that did not happen. See principle 4. This is the one failure mode that does not look broken.

The shape of the thing

build/          the pipeline — build/tudo.py runs every step in the right order
  gates.py          gates 1–15, deny-listed
  gates_artigos.py  gates 16–26 and 34–38, where new gates go
  gates_desenho.py  gates 27–33, the design review's measurements
  before_push.py    what another session did while you worked — read-only
admin/build/    validate.js (the site gate) and render.mjs (the browser gate)
dados/          the data the site is built from. Portuguese keys — see language.md
fontes/congeladas/  frozen bytes. Evidence, never pages. Extension is .snapshot for that reason
artigos/<yyyy>/<mm>/<dd>/<slug>/   an article is a folder, not a file
agents/         one folder per named agent: ROLE.md, MANDATE.md, agent.json
docs/guidance/  this
redacao/        the newsroom: issues, mail, run records, editorial decisions

If you are blocked

Write to redacao/correio/editor/entrada/<timestamp>__<agent>__<subject>.md and stop. A run that stops honestly is a good run. Do not work around a gate, do not widen your own permissions, and do not fix work that is not yours.

The language rule →

This page is rendered from docs/guidance/index.md by build/guia.py. The markdown is the source; edit that and rebuild. Nobody hand-edits this file.

For an agent. Generated by build/newsroom.py from the files in this repository; nothing here is hand-written. The machine-readable index of the publication is at llms.txt. Source: github.com/SGit-AI/SGit-AI__Website__Newsroom__PT · file: newsroom/guidance/index.html · version v0.23.6.