intelligencesupport

Web

Add a site's GitHub repository, fill its queue of briefs, and let the Web editor research, write, translate, and publish each page by pull request.

For
Administrators and editors
In the app
/web/web/[id]
Updated

Watch the video

Let the Web module write and publish articles on your site

Web publishes the pages of your websites. Each site is the GitHub repository it’s built from. You give it a queue of briefs, and an AI agent, the Web editor, takes each brief from research to a page that’s live on the site. Every page reaches the site through a pull request, and that pull request merges only once the site’s own checks pass.

This article is for the administrators and editors who run a site. Web belongs to organizations: open Web in the Studio pillar of the left menu.

What you need first

Two things. Your role needs the Web right (see who can do what). And you need your own GitHub connection.

That connection lives on My Connections, under Your website repositories, or right on the Web page. It goes through the BearingBridge GitHub App in two steps:

  1. Install the GitHub App on your repository: on GitHub, pick your user or organization account and grant access to the website repository you want to publish.
  2. Authorize and connect your GitHub account: click Connect GitHub, approve the sign-in handshake, and you land back on the Web page with your repositories ready to pick.

Your GitHub account needs write access to the repository: publishing is writing.

Add a site

  1. Click Add a site in the page band.
  2. Under Repository, pick one of the repositories your GitHub connection reaches. Missing one? Click Give the app another repository on GitHub, add it there, then come back.
  3. Give the site a Name. The Address of the site is optional, and so is the Brand: leave Whole organization to keep the site outside any brand.
  4. Click Add the site.

The site’s studio opens on its four tabs: Queue & Test Run, AI Editorial Plan, Repository Files & AI Studio, and Site Settings. When the repository already has a schedule file or a briefs folder, its queue is imported right away.

The settings come from the repository

The app reads the repository and proposes the settings. It looks for the names editorial repositories tend to use: a CLAUDE.md or AGENTS.md, a voice brief, a spec, a runbook, a claims ledger, a schedule CSV, a briefs folder, one folder and one translation brief per language. Check every field in the Site Settings tab, fix what’s wrong, and click Save Site Settings. Re-detect from repository reads the paths again after the repository changes, and leaves your instructions and switches alone.

PartFieldsWhat they do
TopSite Name, Live Website URL, Publishes as, Target Branch, Default AI Model, Briefs per scheduled run, Site-Wide Extra ContextWho commits, the branch pull requests go into, the default model for drafts and AI tools, and standing context passed to every step.
SwitchesSite is Active, 18-Pass Editorial Quality Gate, Auto-Publish after Review, Auto-Merge PR on Green ChecksWhether scheduled runs take the site, whether drafts get the full 18-pass edit, whether a draft needs a person at review, and whether the pull request merges itself.
Repository Paths & Editorial FilesRule & Context Files, Verified Sources / Claims Ledger, Schedule CSV File, Briefs Folder, Published Pages Folder, Drafts Output Folder, Hero Images FolderWhere everything lives. Click any file chip to open or create it in the Repository Files & AI Studio tab. Leave Hero Images Folder empty and there’s no hero image step.
LanguagesSource Language Label, Locale Code, Target LanguagesThe source language, then one line per extra language: code, name, folder, and translation brief.
Instructions & Git NamingDraft runs, Publish runs, House line for hero images, Branch prefix, Commit message, Also notifyWhat a draft or publish run touches besides the page, the visual style of hero images (each with a Draft with AI from repository button), and how branches, commits, and emails work.

The site’s rules stay in its repository, not in the app. You can view, edit, create, or update every one of those files with AI in the Repository Files & AI Studio tab, and commit your changes straight to the site’s branch.

Publishes as names the member whose GitHub connection commits and opens the pull requests. Only members who connected GitHub are listed. Commits carry that person’s name, so GitHub shows who published what.

Fill the queue

The queue holds one brief per page. There are three ways to fill it on the site’s page.

Sync from Schedule CSV reads the Schedule CSV File, a CSV with a brief_id column. A site with no schedule file is read from its Briefs Folder instead, one Markdown brief per file. The app says how many briefs it added and how many it brought up to date.

New Brief opens a form in the Queue & Test Run tab: a Working title, the Main search the page answers, the page’s Slug, an Order date, and the Brief itself. Click Generate / Improve Brief with AI to have the AI write or refine the brief from your site’s voice and rules before you add it.

AI Editorial Plan opens a dedicated tab where you pick an AI model, choose how many articles to plan, and add any topic focus or seasonal context. Click AI-Draft Full Editorial Plan to generate a multi-article schedule complete with working titles, target search queries, slugs, and full Markdown briefs. You can edit any card in the preview, then click Commit Plan to Repository & Add to Queue to write the brief files and schedule rows to GitHub and load them into the queue at once.

The queue has three filters (Open, Published, and All) plus a search box. Briefs are taken in order of their order date, then their place in the queue.

The steps of a brief

Select any brief in the queue to open its control panel on the right. Before starting, you can pick the AI Model for this brief and add Extra Context / Instructions for this brief. Then click Test on this brief (stops at Review) to run a safe test that pauses at Review so you can inspect the draft before any pull request is opened, or click Start full run (or Run Next Brief in the top bar). From then on, the steps run every five minutes on their own, or you can click Run next step now to advance right away.

StepWhat happens
ResearchThe agent reads the site’s rules and looks up primary sources.
DraftIt writes the page in the drafts folder.
18-pass editThe draft goes through 18 editing passes, then a final one that folds in the SEO title, description, and excerpt. The queue shows the count, such as 7/19.
Source recheckEvery source is checked again. A fact the agent can’t confirm at its source is cut.
ReviewThe draft waits for approval, or goes on by itself (see below).
Hero imageThe image is rendered with its alt text. Only when the site has a hero images folder.
Publish preparationThe page moves to the pages folder, and the agent wires in its links, its image, and the related pages the site’s instructions name.
TranslationEach extra language gets three native rewriting passes.
ChecksThe app’s own checks: no open item such as TODO or TBD, no em or en dash in the prose, a frontmatter on every page, every translation present with the same address and fields, no empty file. On a failure, the agent fixes the cause and tries again, twice at most.
Pull requestOne commit with every file, on its own branch, and a pull request on the site’s branch.
Site checksThe repository’s own checks run on the pull request.
PublishedThe pull request is merged, and the site deploys from its branch.

One brief of a site is drafted at a time, and one is published at a time, so two publications never touch the same files at once. If a brief is already being written, Start the next brief says there’s nothing to start.

Review

What happens at Review depends on the Publishes on its own switch. With it on, a draft whose sources were rechecked goes on to publication by itself. With it off, it waits for a person with the right to update: Approve and publish sends it on.

A draft the site’s rules hold back shows Waits with the reason. The agent’s next scheduled run tries it again.

Listen versions and discussions

Two switches of Site Settings give each new page its sound:

  • Listen version: the published page is read aloud in the voice of the site’s brand (its sonic brand kit). A page in another language than the kit’s is read by a native speaker of that language, of the same gender.
  • Two-voice discussion: two hosts talk the page through in two to three minutes, from what the page says and nothing else.

When either is on, the brief takes one more step, Listen version, after the translations. The MP3 files are saved in the Audio folder of the settings, named after the page (<page>.mp3 and <page>-discussion.mp3), exactly as the hero image is. Left empty, the folder is public/audio, the folder Astro, Next.js and Vite sites serve as they are. The page and each of its translations get an audio and a discussion field in their frontmatter, for a template that draws its own player, and a plain HTML player under their title, which any Markdown site shows as it is, with its words in the page’s language. Everything goes in the same pull request as the page.

A page already published gets its listen version from its brief: open it in the queue and click Make the listen version. It makes what the site has switched on (the listen version alone when neither switch is on), commits the MP3 files and the players in a pull request of their own, and the page stays published, with its date, throughout. The recording is billed like the rest of the Web editor’s work and added to the brief’s cost.

Publishing through a pull request

Nothing in the repository changes before the Pull request step. Until then, every file the run writes is kept in the app, and you can open each one from the brief’s Files tab.

At that step, the app makes one commit with every file of the brief on a new branch, named after the Branch prefix and the page’s address (bb/ followed by the address, unless you change it). It opens a pull request on the site’s branch and lists every file in it. If the site has a schedule file, the brief’s row is updated in the same commit.

Then the repository’s checks run. When they pass and Merges on green checks is on, the pull request merges itself and the branch is deleted. With the switch off, the pull request waits on GitHub for someone to merge it, and the brief shows Published once that happens.

When the checks fail, the agent reads why, fixes the cause, and pushes again. It tries twice. After that, the brief stops. A repository with no checks at all is merged on the app’s own checks after ten minutes. Checks still running after 90 minutes stop the brief too.

Once a page is live, an email goes to the site’s publisher and to whoever started the brief, plus any address under Also tell. It names the site, the page, the brief, the pull request, the languages, and what the brief cost. Each reader gets it in their own language.

When a brief stops

The Web editor never leaves an item open. A fact it can’t confirm is researched or cut, not flagged for later. When a step can’t close something, the brief stops at Stopped, the reason shows at the top of its detail, and nothing of it is published.

Common reasons: the checks still fail after two fixes, the pull request was closed without being merged, the site has no publisher, or the publisher’s GitHub connection is gone. A one-off glitch, such as a model call that times out, is retried at the next run, three times before the brief stops.

Fix the cause, then click Take it again. The brief starts over at the step where it stopped.

Note: When the organization’s spending limit is reached, a brief doesn’t stop. It pauses, and carries on once there’s room again.

Follow a brief

Click a brief in the queue to open its detail beside it: the steps, with the current one highlighted, then the facts and the actions.

  • Log: every step, with the time and what the agent did or found.
  • Versions: the text after every pass, from the first draft to each translation pass. Click one to read it.
  • Files: every file the run wrote, deleted ones included. Click one to read it, or to see the image.
  • Brief & AI: the brief’s own Markdown file, where you can view, edit, or improve it with AI and commit your changes to the repository.

The detail also links to the pull request, such as Pull request #42, and shows the brief’s Cost so far.

Other actions depend on where the brief is. Skip sets a brief aside, and Back to the queue brings it back. Remove takes it out of the queue. A brief that’s being published can’t be skipped or removed until its pull request is finished.

The Web editor agent

Starting briefs by hand works fine. To keep a site publishing on a schedule, add the Web editor from the agent catalog. Like every standard agent, it does nothing until someone adds it. Its catalog code is MK13, and it runs every 24 hours by default.

Each scheduled run starts the next brief of every active site. On a site that publishes on its own, it also sends on the drafts waiting at review. On one that doesn’t, its findings list the drafts that still need approval. Untick Active in a site’s settings and the agent’s runs leave that site alone.

For each brief, the Web editor uses the AI Model for this brief if you picked one, then the site’s Default AI Model, then the model picked on the agent, and finally your organization’s model for Web under Content on the AI models page (or Claude Opus after that). Hero images are rendered by an image model of their own.

The skills it applies

The editing and translation passes follow four standard skills, in the Web publishing group of the skills catalog. They apply where it says Web:

SkillWhat it sets
Newsroom standard (US English)The rules of every edit: American newsroom prose, US spelling, no em dash, no invented fact.
Native translation standardEvery translated page reads as written by a native journalist, with the language’s own punctuation and the SEO fields rewritten.
AI tells to removeThe patterns that make text read machine-written, hunted by the edit and translation passes.
Hero image standardWhat a hero image looks like, and its alt text in every language.

They apply as shipped until your organization adds one to its skills and rewrites it. The publisher’s own version of a skill wins over the organization’s. A site’s own rule files still win wherever they’re stricter. See skills.

What it costs

Every model call, web search, and image of a brief’s run is counted on that brief. The queue shows the running total on each row, and the detail shows it as Cost: the price billed to you, everything included. The publication email repeats it.

The runs are charged to your organization, whoever started the brief, and appear in the usage log as Web · page researched, written and published. A brief’s progress also shows in Activity while it runs. Adding a site, importing a queue, and writing a brief cost nothing.

Remove a site or a brief

Remove this site, at the foot of the settings, takes the site and its queue out of the app. Remove on a brief takes that brief out of the queue. Neither touches the repository: its pages, briefs, and schedule stay where they are. A site can’t be removed while one of its pages is being published.

Disconnecting GitHub on My Connections stops every site that publishes with your connection, until someone connects again and is named under Publishes as.

Who can do what

Web has its own row in the rights grid. See roles and rights.

RightWhat it allows
ViewOpen the Web page, the sites and their queues.
CreateAdd a site, write a brief, or start one.
UpdateImport the queue, change a site’s settings, run the next step, approve, take again, or skip a brief.
DeleteRemove a site or a brief, never anything in the repository.

Web is for members of an organization.