docs: consolidate factory-first references and retire outdated guidance

.agents/skills/draft_feature_doc/SKILL.md

@@ -50,4 +50,4 @@ For any product name in `src/data/vars.ts`, use the variable — never hardcode
 
 Read 2-3 of these strong examples to match the existing pattern:
 - `src/content/docs/agents/capabilities/skills.mdx`
-- `src/content/docs/platform/environments.mdx`
+- `src/content/docs/factories/environments.mdx`

.agents/skills/missing_docs/references/consistency_seeds.json

@@ -157,11 +157,11 @@
         "../warp-server/billing/config/tiers/_base_self_serve_plan.yaml"
       ],
       "affected_surfaces": [
-        "src/content/docs/platform/harnesses/index.mdx",
+        "src/content/docs/factories/harnesses/index.mdx",
         "src/content/docs/support-and-community/plans-and-billing/pricing-faqs.mdx"
       ],
       "surface_dispositions": {
-        "src/content/docs/platform/harnesses/index.mdx": "fixed",
+        "src/content/docs/factories/harnesses/index.mdx": "fixed",
         "src/content/docs/support-and-community/plans-and-billing/pricing-faqs.mdx": "fixed"
       },
       "recheck_condition": "Harness entitlements change in shipped tier configuration.",
@@ -381,12 +381,10 @@
       ],
       "affected_surfaces": [
         "src/content/docs/agents/cli/oz-cli/index.mdx",
-        "src/content/docs/platform/faqs.mdx",
         "src/content/docs/agents/local-agents/agent-context/images-as-context.mdx"
       ],
       "surface_dispositions": {
         "src/content/docs/agents/cli/oz-cli/index.mdx": "fixed",
-        "src/content/docs/platform/faqs.mdx": "fixed",
         "src/content/docs/agents/local-agents/agent-context/images-as-context.mdx": "fixed"
       },
       "recheck_condition": "Legacy CLI attachment validation or interactive image input paths change.",
@@ -402,7 +400,6 @@
           "type": "forbidden_text",
           "patterns": ["Cloud agent conversations do not currently support image attachments"],
           "paths": [
-            "src/content/docs/platform/faqs.mdx",
             "src/content/docs/agents/local-agents/agent-context/images-as-context.mdx"
           ]
         }
@@ -568,18 +565,18 @@
       "status": "owner_confirmation",
       "occurrence_queries": ["Concurrency limits", "credit allocation details", "still being finalized"],
       "authoritative_sources": [],
-      "affected_surfaces": ["src/content/docs/platform/faqs.mdx"],
-      "surface_dispositions": {"src/content/docs/platform/faqs.mdx": "blocked"},
+      "affected_surfaces": ["src/content/docs/platform/team-access-billing-and-identity.mdx"],
+      "surface_dispositions": {"src/content/docs/platform/team-access-billing-and-identity.mdx": "blocked"},
       "owner": "Product and Billing",
-      "unresolved_question": "What current public concurrency and credit-allocation guidance should replace the placeholder, or should the placeholder be removed without replacement?",
+      "unresolved_question": "The stale FAQ placeholder was removed during article consolidation. What current public concurrency and credit-allocation guidance belongs on the access and billing owner, or should it remain omitted? Removing the placeholder does not resolve this owner-confirmation finding.",
       "recheck_condition": "Product and Billing approve replacement guidance or approve removing the placeholder.",
-      "inconsistent_surfaces": ["src/content/docs/platform/faqs.mdx"],
+      "inconsistent_surfaces": ["src/content/docs/platform/team-access-billing-and-identity.mdx"],
       "deterministic_rules": [
         {
           "id": "no-finalizing-concurrency-placeholder",
           "type": "forbidden_regex",
           "patterns": ["Concurrency limits\\s+and\\s+credit allocation details\\s+are\\s+still being finalized"],
-          "paths": ["src/content/docs/platform/faqs.mdx"]
+          "paths": ["src/content/docs/platform/team-access-billing-and-identity.mdx"]
         }
       ]
     },

.agents/skills/missing_docs/references/feature_surface_map.md

@@ -191,7 +191,7 @@ ArtifactCommand -> src/content/docs/agents/cli/oz-cli/artifacts.mdx
 OzIdentityFederation -> src/content/docs/agents/cli/oz-cli/federate.mdx
 
 # Third-party harness support
-AgentHarness -> src/content/docs/platform/harnesses/index.mdx
+AgentHarness -> src/content/docs/factories/harnesses/index.mdx
 
 # Image context for cloud agents
 AmbientAgentsImageUpload -> src/content/docs/agents/local-agents/agent-context/images-as-context.mdx

.agents/skills/missing_docs/scripts/test_audit_docs.py

@@ -311,24 +311,34 @@ def test_approved_seed_store_partitions_all_24_findings(self):
         )
         self.assertEqual(result["accounting"]["unaccounted"], [])
 
-    def test_current_placeholder_remains_a_deterministic_finding(self):
+    def test_removed_placeholder_keeps_owner_confirmation_at_canonical_owner(self):
         result = audit_docs.audit_consistency(_DOCS_ROOT)
         findings = [
             item
             for item in result["findings"]
             if item["seed_id"] == "cloud-concurrency-placeholder"
         ]
-        self.assertEqual(len(findings), 1)
-        self.assertEqual(findings[0]["rule_id"], "no-finalizing-concurrency-placeholder")
-        self.assertEqual(findings[0]["path"], "src/content/docs/platform/faqs.mdx")
+        self.assertEqual(findings, [])
+        blockers = [
+            item for item in result["blockers"]
+            if item["seed_id"] == "cloud-concurrency-placeholder"
+        ]
+        self.assertEqual(len(blockers), 1)
+        self.assertEqual(blockers[0]["status"], "owner_confirmation")
+        self.assertEqual(blockers[0]["owner"], "Product and Billing")
+        self.assertEqual(blockers[0]["inconsistent_surfaces"], [
+            "src/content/docs/platform/team-access-billing-and-identity.mdx"
+        ])
+        self.assertTrue(blockers[0]["unresolved_question"])
+        self.assertTrue(blockers[0]["recheck_condition"])
 
     def test_resolved_statements_pass_their_rules(self):
         result = audit_docs.audit_consistency(_DOCS_ROOT)
         passed = {item["rule_id"] for item in result["rules"]["passed"]}
         self.assertIn("no-singular-create-run-example", passed)
         self.assertIn("no-five-file-cli-limit", passed)
         self.assertIn("no-old-session-sharing-links", passed)
-        self.assertNotIn("no-finalizing-concurrency-placeholder", passed)
+        self.assertIn("no-finalizing-concurrency-placeholder", passed)
 
     def test_policy_blockers_remain_visible_with_owner_metadata(self):
         result = audit_docs.audit_consistency(_DOCS_ROOT)

.github/workflows/ci.yml

@@ -156,6 +156,11 @@ jobs:
       - name: Validate page title order
         run: npm run test:page-title-order
 
+      - name: Validate migrated references and retired articles
+        run: |
+          npm run test:platform-reference-migration
+          npm run test:article-retirements
+
       - name: Check internal links
         run: python3 .agents/skills/check_for_broken_links/check_links.py --internal-only
       - name: Test redirect invariants

AGENTS.md

@@ -800,7 +800,7 @@ This is the most common page type in Warp's docs (~75+ pages). A feature documen
 
 Past roughly 1500 words, cut padding and repeated sibling-page content first. Split only if the remaining useful content still needs separate pages; preserve necessary facts by linking or relocating them.
 
-**Existing examples**: `agents/capabilities/skills.mdx`, `platform/environments.mdx`
+**Existing examples**: `agents/capabilities/skills.mdx`, `factories/environments.mdx`
 
 **Template**: `.agents/templates/feature-doc.md`
 

astro.config.mjs

@@ -220,9 +220,9 @@ export default defineConfig({
 					customSets: [
 						{ label: 'Terminal', description: 'Warp Terminal features and configuration.', paths: ['terminal/**'] },
 						{ label: 'Agents', description: 'Agents in Warp: capabilities, local agents, and CLI agents.', paths: ['agents/**'] },
-						{ label: 'Factories', description: 'Warp Factories documentation for setup, agent roles, definitions as code, integrations, measurement, and infrastructure.', paths: ['factories/**'] },
+						{ label: 'Factories', description: 'Warp Factories setup, agents, integrations, measurement, and shared cloud harness, environment, and MCP-server references.', paths: ['factories/**'] },
 						{ label: 'Warp Agent CLI', description: 'The Warp Agent CLI: agent conversations, shell commands, permissions, and configuration in any terminal.', paths: ['agents/cli/**'] },
-						{ label: 'Automation Platform', description: 'The Automation Platform: cloud agents, orchestration, triggers, integrations, environments, harnesses, and self-hosting.', paths: ['platform/**'] },
+						{ label: 'Automation Platform', description: 'Factory-first entry points and supported standalone cloud-agent workflows, orchestration, triggers, integrations, and legacy configuration.', paths: ['platform/**'] },
 						{ label: 'Code', description: 'Code editor, code review, and Git worktrees.', paths: ['code/**'] },
 						{ label: 'Enterprise', description: 'Enterprise features, SSO, team management, and security.', paths: ['enterprise/**'] },
 						{ label: 'Getting Started', description: 'Installation, quickstart, and migration guides.', paths: ['index', 'quickstart', 'getting-started/**'] },

package.json

@@ -26,6 +26,8 @@
     "test:kapa-webmcp": "node --test src/lib/kapa-webmcp.test.mjs",
     "test:kapa-support-escalation": "node --test src/lib/kapa-support-escalation.test.mjs",
     "test:homepage-json-ld": "node scripts/validate-homepage-json-ld.mjs",
+    "test:platform-reference-migration": "node scripts/validate-platform-reference-migration.mjs",
+    "test:article-retirements": "node scripts/validate-article-retirements.mjs",
     "test:page-title-order": "node scripts/validate-page-title-order.mjs",
     "postinstall": "patch-package"
   },