[codex] Add AI company OS docs pillar page

docs/guides/welcome/what-is-an-ai-company-operating-system.md

@@ -0,0 +1,98 @@
+# What is an AI company operating system?
+
+An **AI company operating system** (AI company OS) is software that runs a team of AI agents the way a company runs employees: it gives each agent a role and a manager, assigns work through a shared task board, enforces budgets and approval gates, and keeps a full audit trail of everything the agents do. Where an agent framework helps you build a single agent, an AI company OS coordinates many agents — and keeps a human in charge of the decisions that matter.
+
+---
+
+## Why the category exists
+
+One AI agent is easy to run. You give it a prompt, it does a task, you read the result.
+
+Ten agents working toward one goal is a different problem. Someone has to decide who does what, stop two agents from doing the same work twice, notice when work stalls, escalate blockers, cap spending, and answer for what happened afterwards. Those are not model problems — they are *organizational* problems, and they are the same ones human companies solved with org charts, managers, budgets, and review processes.
+
+An AI company operating system applies that structure to agents. It is not the AI itself; it is the layer above the AI — the org chart, the task board, the budget controller, and the audit trail that turn a pile of agents into a working organization.
+
+## The core components
+
+Most AI company operating systems share six building blocks:
+
+### 1. An org structure with roles and reporting lines
+
+Agents are hired into roles — CEO, engineer, QA, analyst — and every agent reports to exactly one manager. Delegation flows down the chain; escalation flows up it. This is what makes the system scale: adding a tenth agent doesn't add coordination work for the human, because coordination is the managers' job.
+
+### 2. A shared task board with ownership
+
+Work lives in tasks with a status, a priority, an assignee, and a comment thread. Exclusive checkout prevents two agents from claiming the same task at once, and every task traces back to a company goal, so nothing runs without a reason.
+
+### 3. An execution model
+
+Agents don't run as unbounded loops. In Paperclip's case they wake in **heartbeats** — short, logged execution windows in which an agent checks its inbox, does a bounded chunk of work, posts an update, and stops. Bounded execution is what makes agent work inspectable, interruptible, and affordable.
+
+### 4. Governance and approvals
+
+Certain actions — hiring a new agent, adopting a strategy, spending past a threshold, posting publicly — pause and wait for sign-off. The human operator (the *board*) reviews and approves, rejects, or asks for changes. Routine work runs autonomously; consequential decisions come to a person.
+
+### 5. Budgets and cost control
+
+Every model call is metered and attributed to an agent and a task. Budgets exist per agent and for the whole company, with warnings as limits approach and hard stops when they are hit. Agents pause when they run out of budget instead of running up a surprise bill.
+
+### 6. Observability and audit
+
+Every heartbeat produces a transcript. Every task carries its comment history. When you want to know *why* an agent did something, you read the run — not guess from the output.
+
+## What an AI company OS is not
+
+The category is easiest to define by contrast:
+
+- **Not an agent framework.** Frameworks (LangChain, CrewAI, the OpenAI Agents SDK) are libraries for *building* an agent or a scripted multi-agent pipeline. An AI company OS is a *runtime and management layer* for agent teams — it doesn't care which framework or model powers each agent, and different agents in one company can run on different AI systems entirely.
+- **Not a single autonomous agent.** Tools that run one powerful agent in a loop hit a ceiling when work needs parallelism, review, or specialized context. A company OS is a team abstraction, not a bigger assistant.
+- **Not a project management tool with an agent inside.** Issue trackers and knowledge bases are adding built-in agents, which is useful — but the tool remains the product and the agent a feature. In an AI company OS, the organization is the product: roles, budgets, governance, and execution are first-class.
+- **Not workflow automation.** Automation platforms execute predefined flows. Agents in a company OS are given goals and figure out the steps, with the OS supplying guardrails rather than a fixed script.
+
+For concrete side-by-side comparisons, see [Paperclip vs Multica](https://paperclip.ing/vs/multica), [Paperclip vs Cabinet](https://paperclip.ing/vs/cabinet), [Paperclip vs Notion Agents](https://paperclip.ing/vs/notion-agents), and [Paperclip vs Linear Agents](https://paperclip.ing/vs/linear-agents).
+
+## What running one looks like
+
+A typical loop, using Paperclip as the example:
+
+1. **You set a goal** — "Ship the MVP by Q2", "Keep the docs site accurate and growing".
+2. **A CEO agent proposes a strategy.** The proposal arrives as an approval; nothing executes until you sign off.
+3. **Work flows down the org chart.** The CEO creates projects and tasks and delegates to its reports; managers delegate further.
+4. **Agents execute in heartbeats.** They check out tasks, do the work, post progress in the task thread, and hand off to QA or reviewers.
+5. **Exceptions come to you.** Hires, budget overrides, external actions, and anything an agent can't resolve escalate to the board as approvals or blocked tasks.
+6. **You audit at your leisure.** Dashboards show status and spend; run history shows exactly what any agent did and why.
+
+The human's job shifts from *doing* the work — or even assigning it — to setting direction and judging the results.
+
+## When you need one
+
+You probably don't need an AI company OS for a single assistant or a one-shot automation. The category earns its keep when:
+
+- **More than a couple of agents** work toward the same goal and start colliding or duplicating work.
+- **Work must survive nobody watching** — tasks progress overnight and blockers surface as escalations instead of silent stalls.
+- **Money is at stake** — you need per-agent spending limits and attribution, not one shared API key.
+- **Accountability matters** — you need to show what an agent did, when, and under whose approval.
+- **The team is heterogeneous** — some agents run on Claude, some on other models or vendors' systems, and they need to work under the same coordination rules.
+
+## Frequently asked questions
+
+**Is an AI company OS the same as multi-agent orchestration?**
+Orchestration is one part of it — the routing of work between agents. A company OS adds the parts orchestration frameworks leave out: persistent roles and reporting lines, budgets, human approval gates, and audit trails.
+
+**Do the agents have to come from one vendor?**
+No. The OS manages agents through adapters, so a single company can mix agents powered by different AI systems, each with the same task board, budget, and governance rules.
+
+**Where do humans fit?**
+At the top. The human operator owns the goal, approves strategy and hires, controls budgets, and can override any agent or task. Day-to-day execution is autonomous; authority is not.
+
+**Is this the same as "agentic workflow" tools?**
+Workflow tools execute steps you define in advance. An AI company OS assigns *outcomes* and lets agents plan the steps, with governance around the edges.
+
+---
+
+## Learn more
+
+- [What is Paperclip?](./what-is-paperclip.md) — how Paperclip implements the AI company OS
+- [Key Concepts](./key-concepts.md) — companies, agents, tasks, heartbeats, and approvals in depth
+- [Glossary](./glossary.md) — every term, in plain English
+- [Run your first company in five minutes](../getting-started/five-minute-path.md)

scripts/verify-static-routes.mjs

@@ -84,11 +84,51 @@ try {
   assert(glossaryHtml.includes('<h3 id="board-operator">Board Operator</h3>'), "glossary route is missing the Board Operator term anchor");
   assert(glossaryHtml.includes('<h3 id="heartbeat">Heartbeat</h3>'), "glossary route is missing the Heartbeat term anchor");
 
+  const aiCompanyOsPath = "guides/welcome/what-is-an-ai-company-operating-system/index.html";
+  assert(existsSync(join(outDir, aiCompanyOsPath)), `missing ${aiCompanyOsPath}`);
+  const aiCompanyOsHtml = read(aiCompanyOsPath);
+  assert(
+    aiCompanyOsHtml.includes("<title>What is an AI Company Operating System? | Paperclip Docs</title>"),
+    "AI company OS route did not get a route-specific title",
+  );
+  assert(
+    aiCompanyOsHtml.includes('content="An AI company operating system (AI company OS) is software that runs a team of AI agents'),
+    "AI company OS route did not use the opening definition for its meta description",
+  );
+  assert(
+    aiCompanyOsHtml.includes('href="/guides/welcome/what-is-paperclip/"'),
+    "AI company OS page did not rewrite ./what-is-paperclip.md to its route",
+  );
+  assert(
+    aiCompanyOsHtml.includes('href="/guides/welcome/key-concepts/"'),
+    "AI company OS page did not rewrite ./key-concepts.md to its route",
+  );
+  assert(
+    aiCompanyOsHtml.includes('href="/guides/welcome/glossary/"'),
+    "AI company OS page did not rewrite ./glossary.md to its route",
+  );
+  assert(
+    aiCompanyOsHtml.includes('href="/guides/getting-started/five-minute-path/"'),
+    "AI company OS page did not rewrite ../getting-started/five-minute-path.md to its route",
+  );
+  assert(
+    aiCompanyOsHtml.includes('href="https://paperclip.ing/vs/multica"'),
+    "AI company OS page should preserve absolute comparison links",
+  );
+  assert(!aiCompanyOsHtml.includes('href="./what-is-paperclip.md"'), "AI company OS static page still links to ./what-is-paperclip.md");
+  assert(!aiCompanyOsHtml.includes('href="./key-concepts.md"'), "AI company OS static page still links to ./key-concepts.md");
+  assert(!aiCompanyOsHtml.includes('href="./glossary.md"'), "AI company OS static page still links to ./glossary.md");
+  assert(!aiCompanyOsHtml.includes('href="../getting-started/five-minute-path.md"'), "AI company OS static page still links to ../getting-started/five-minute-path.md");
+
   const appJs = read("app.js");
   assert(!appJs.includes("/#/"), "generated app JS still contains primary hash route URLs");
 
   const sitemap = read("sitemap.xml");
   assert(sitemap.includes("https://docs.paperclip.ing/reference/skills"), "sitemap is missing reference/skills");
+  assert(
+    sitemap.includes("https://docs.paperclip.ing/guides/welcome/what-is-an-ai-company-operating-system"),
+    "sitemap is missing the AI company OS pillar page",
+  );
   assert(
     existsSync(join(outDir, "reference/skills/bundled/index.html")),
     "missing reference/skills/bundled/index.html",

site/build-release.mjs

@@ -516,6 +516,31 @@ function slugifyHeadingText(text) {
     .replace(/-+/g, "-");
 }
 
+function markedLinkArgs(args, renderer) {
+  const [hrefOrToken, title, text] = args;
+  if (hrefOrToken && typeof hrefOrToken === "object") {
+    const token = hrefOrToken;
+    return {
+      href: token.href || "",
+      title: token.title || "",
+      text: Array.isArray(token.tokens) && renderer?.parser
+        ? renderer.parser.parseInline(token.tokens)
+        : token.text || "",
+    };
+  }
+  return { href: hrefOrToken || "", title: title || "", text: text || "" };
+}
+
+function releaseMarkdownLinkForPage(page, pages, basePath) {
+  return function releaseMarkdownLink(...args) {
+    const { href, title, text } = markedLinkArgs(args, this);
+    const rewrittenHref = rewriteLocalMarkdownHref(href, page, pages, basePath);
+    const attrs = [`href="${escapeAttr(rewrittenHref)}"`];
+    if (title) attrs.push(`title="${escapeAttr(title)}"`);
+    return `<a ${attrs.join(" ")}>${text}</a>`;
+  };
+}
+
 function markdownToPlainText(markdown) {
   return markdown
     .replace(/```[\s\S]*?```/g, " ")
@@ -553,6 +578,26 @@ function routeUrlForPage(siteUrl, basePath, page) {
   return siteUrlForPath(siteUrl, basePath, `${page.slug}/`);
 }
 
+function routeHrefForPage(basePath, page, heading = "") {
+  const publicBasePath = basePath === "auto" ? "/" : basePath;
+  const suffix = heading ? `#${heading}` : "";
+  return `${publicBasePath}${page.slug}/${suffix}`;
+}
+
+function rewriteLocalMarkdownHref(href, currentPage, pages, basePath) {
+  if (!href || !isLocalDocHref(href)) return href;
+
+  const hashIndex = href.indexOf("#");
+  const docHref = hashIndex === -1 ? href : href.slice(0, hashIndex);
+  const headingHref = hashIndex === -1 ? "" : href.slice(hashIndex + 1);
+  if (!docHref.endsWith(".md")) return href;
+
+  const baseDir = currentPage.file.replace(/\/[^/]+$/, "/");
+  const targetFile = normalizeDocPath(baseDir + docHref);
+  const targetPage = pages.find((page) => page.file === targetFile);
+  return targetPage ? routeHrefForPage(basePath, targetPage, headingHref) : href;
+}
+
 function buildJsonLd(metadata) {
   const graph = metadata.page
     ? {
@@ -933,10 +978,11 @@ function preprocessTabs(markdown) {
   return output;
 }
 
-function renderStaticMarkdown(markdown) {
+function renderStaticMarkdown(markdown, page, pages, basePath) {
   const renderer = new marked.Renderer();
   const usedHeadingIds = new Set();
   renderer.image = releaseMarkdownImage;
+  renderer.link = releaseMarkdownLinkForPage(page, pages, basePath);
   renderer.heading = (html, level, rawText) => {
     const baseId = slugifyHeadingText(rawText) || `h${level}`;
     let id = baseId;
@@ -956,8 +1002,8 @@ function inlineReleaseStyles(html, css) {
   );
 }
 
-function buildStaticPageHtml(sourceIndex, metadata, markdown, basePath, releaseStyles) {
-  const articleHtml = renderStaticMarkdown(markdown);
+function buildStaticPageHtml(sourceIndex, metadata, markdown, basePath, releaseStyles, pages) {
+  const articleHtml = renderStaticMarkdown(markdown, metadata.page, pages, basePath);
   const routeBaseHref = basePath === "auto" ? "/" : basePath;
   return inlineReleaseStyles(injectSeo(sourceIndex, metadata, { baseHref: routeBaseHref }), releaseStyles)
     .replace('<section id="landing">', '<section id="landing">')
@@ -967,6 +1013,7 @@ function buildStaticPageHtml(sourceIndex, metadata, markdown, basePath, releaseS
 }
 
 async function writeStaticRoutePages({ outDir, sourceIndex, pages, markdownBodiesByFile, basePath, releaseStyles }) {
+  const navPages = pages.map((metadata) => metadata.page);
   for (const metadata of pages) {
     const { page } = metadata;
     const markdown = markdownBodiesByFile.get(page.file);
@@ -976,7 +1023,7 @@ async function writeStaticRoutePages({ outDir, sourceIndex, pages, markdownBodie
       throw new Error(`Refusing to write route outside release directory: ${page.slug}`);
     }
     await ensureDir(path.dirname(routePath));
-    await fs.writeFile(routePath, buildStaticPageHtml(sourceIndex, metadata, markdown, basePath, releaseStyles));
+    await fs.writeFile(routePath, buildStaticPageHtml(sourceIndex, metadata, markdown, basePath, releaseStyles, navPages));
   }
 }
 

site/content.json

@@ -14,6 +14,10 @@
           "title": "What is Paperclip?",
           "file": "../docs/guides/welcome/what-is-paperclip.md"
         },
+        {
+          "title": "What is an AI Company Operating System?",
+          "file": "../docs/guides/welcome/what-is-an-ai-company-operating-system.md"
+        },
         {
           "title": "Key Concepts",
           "file": "../docs/guides/welcome/key-concepts.md"