Confluence content migration to bewith-docs

ClaimedAuthor: @relbnsOwner: @relbnsEffort: L (phased)

Problem

The team's institutional knowledge sits in Confluence — ~365 substantive pages across the WITH team space and one de-facto PM personal space. Bewith-docs has become the platform's source of truth for methodology, decisions, and AI artifacts, but the content the team actually consults day-to-day (architecture, security, onboarding, runbooks, specs) is still in Confluence. The split creates three problems:

1. Discoverability cost. Engineers (and Claude sessions) have to know to check both. The capability-index in bewith-docs has no idea that "Cloud Security Overview" exists in Confluence.
2. AI accessibility. Claude Code can read bewith-docs naturally (via the plugin). Confluence access requires MCP permissions that are not always present in subagent contexts (see /tmp/confluence-survey-2026-05-31.md §"MCP coverage gap").
3. Stale-by-default. Confluence pages drift because nobody owns them; the bewith-docs PR review model would catch the same drift in a contribution flow.

A survey on 2026-05-31 mapped what exists. The output (in /tmp/confluence-survey-2026-05-31.md) identifies 20 load-bearing pages, 4 major de-dup clusters, and ~70% of pages recommended to stay in Confluence (sprints, retros, interviews, HR, training records, deprecated pages, per-client RSS mappings).

Proposal

Migrate the load-bearing Confluence content into bewith-docs in five phases, each shippable independently. Each migrated page lands at a predictable path; broken cross-references resolve through a redirect map; Hebrew content gets translated or stays in Confluence per the artifact-language rule.

The migration is selective, not lift-and-shift. Most pages stay in Confluence. The goal is to move the ~30% that have durable engineering value.

Why now / Why us

• Engineers are about to onboard the platform. PR #29 lands CONTRIBUTING.md + onboarding quickstart. The first time a new contributor reads "where do I find architecture?", they should land in bewith-docs — not bounce to Confluence.
• Confluence is closing the gap on us. The recent May-2026 burst of pages (General Architecture Specification, Domain Entities, Ownership matrix, AI - Roadmap, AI-Driven SDLC) is the team writing exactly the content bewith-docs aims to be authoritative for. Without migration, two sources will compete.
• Bewith-docs is the only tool that can enforce conventions. Confluence is a wiki — no PR review, no CI, no link validation, no schema. Bewith-docs is the only place that can run validate-pr against content changes.

Sketch of approach — five phases

Phase 1 — Load-bearing 20 (effort: M)

Migrate the 20 pages flagged in the survey as load-bearing. Each lands at a specific target path:

#	Confluence page (id)	Target
1	General Architecture Specification (926842882)	docs/architecture/overview.md
2	Domain Entities (945487874)	docs/architecture/domain-entities.md
3	API Endpoints Specification (926351362)	docs/architecture/api/index.md
4	Database Specification (925990914)	docs/architecture/db/index.md
5	Ownership matrix (944930817)	docs/methodology/ownership.md
6	AI-Driven SDLC (948109313)	docs/methodology/ (verify overlap first)
7	AI - Roadmap (948011009)	docs/proposals/
8	With R&D coding conventions (593461252)	docs/methodology/coding-conventions.md (reconcile w/ cursor-rules)
9	Cloud Security Overview (31490089)	docs/security/cloud-security.md
10	Roles and Permissions Design (428703745)	docs/architecture/permissions.md
11	Client-Facing Security Overview (912523266)	docs/security/client-facing-overview.md
12	Macbook setup (15007933)	docs/onboarding/mac-setup.md
13	Environments links (490700804)	docs/onboarding/environments.md
14	Run BE locally against Staging (287015086)	docs/runbooks/local-dev/run-against-staging.md
15	Ngrok proxy localhost (819953665)	docs/runbooks/local-dev/ngrok.md
16	Feature development life cycle (232456194)	docs/methodology/feature-lifecycle.md
17	Public API cluster (400588802 + Get-Communities / Members V1 / Resources stats)	docs/integrations/public-api/
18	Webhook Integration Guide (326631428)	docs/integrations/webhooks.md
19	Notification Templates new infra (498073601)	docs/architecture/notifications.md
20	DB cluster — ERD (818741250) + DB Overview (818348033) + DB collections (851673089)	docs/architecture/db/ (consolidated)

For each page: read via confluence_get_page, translate Confluence-storage XML to Markdown, attach images as static assets under static/migrated/<id>/, commit with migration: prefix, link in the appropriate sidebar.

Phase 2 — Security & compliance cluster (effort: M)

Migrate the ~12-page security suite together: ISP, SSP, Risk Management, Incident Response, Patch Process, CISA Monitor index, Access Control Matrix, SSDLC. All land under docs/security/.

Confidentiality: Confirm bewith-docs Private Pages + SSO is appropriate for this tier of content before publishing. If not, host security docs in a separate private repo and link.

Training records (SSDLC 2022–2025, Security awareness 2024–2025) — stay in Confluence as compliance audit trail.

Phase 3 — Public API + integrations (effort: S)

Migrate the integrations cluster (~10 pages): Public API root + endpoint pages, Webhook guide, RSS API, External API for Org Users, Min Technical Requirements, AWS Cognito ↔ Azure AD setups (1 canonical + fold older variants). Land under docs/integrations/.

These are externally-shared in spirit but accessed via the Confluence anonymous link today. Decide before migrate whether the new home is public or behind SSO.

Phase 4 — De-dup cluster decisions (effort: M, blocks others)

Before migrating, decide the canonical page for each of four duplicate clusters. Each cluster gets one keep, the rest get folded or archived in Confluence:

Cluster	Pages	Recommended canonical
Coupons	5 pages	Designing a Scalable Coupon Management System (911048705) — newest, sized for the current redesign
Waiting list	2 pages	Waiting List Design Review (756056069) — formal design-review pass
OIDC config	5 pages	AWS Cognito ↔ Azure AD OIDC configuration (544211021) — most recent, AWS-native
Roles & Permissions	8 pages across spaces	Roles and Permissions - Design (428703745) — explicit "design" page, frequently updated
Notifications	8+ pages	TBD — needs Aviad's input; cluster spans 2024–2026, no obvious canonical

Output: a docs/migrations/dedup-decisions.md recording each cluster's resolution, so the migration script knows which pages to skip and which to fold.

Phase 5 — Specs sweep (effort: L, low-urgency)

The WITH space has ~80 feature specs from 2020–2024. The heuristic: if the feature ships today, migrate; otherwise leave in Confluence under an "Archived specs" label. This phase is mechanical but bulky and gates nothing — defer until phases 1–4 are done.

Open questions

• Q1. Does the AI-SDLC (948109313) / AI-Roadmap (948011009) content overlap with what we've already written in docs/methodology/ and docs/proposals/? Verify content before migrating to avoid fork-of-truth.
• Q2. Hebrew content. feedback_artifact_language rule says artifacts must be English. Pages like סקר הרשאות 2025 ספטמבר (761790465), 2024 סקר הרשאות אפריל (301531139), Daily meetings guidelines (Hebrew sections), Permissions From Aviad (mixed) — translate or leave?
• Q3. Image-heavy pages (ERD, architecture diagrams). Migration of attachments is a separate script. Acceptable to ship Phase 1 with text-only and TODO-link the images, or block on full attachment migration?
• Q4. Public vs. private hosting for security/compliance docs. Today bewith-docs is Private Pages + SSO. Sufficient for ISP/SSP/CISA Monitor?
• Q5. Confluence redirect strategy. After migration, old Confluence URLs still resolve (we don't have admin rights to delete). Do we update each migrated Confluence page with a "Migrated to bewith-docs/<path>" banner, or leave the originals alone? Recommendation: banner via a one-time script using confluence_update_page MCP tool.
• Q6. Authority handoff. Once docs/architecture/permissions.md exists, the Confluence original becomes a permanent stale-by-design page. Who's responsible for taking it down? Recommendation: a "deprecated → migrated" Confluence label, scriptable via MCP.
• Q7. MCP permission gap. confluence_get_page was permission-denied in the survey subagent. Action item: verify the main-session permissions include the read tools before Phase 1 starts; otherwise this gets blocked early.

Related

• Survey output: /tmp/confluence-survey-2026-05-31.md (4-minute read — full per-page table)
• docs/methodology/artifact-types.md — decides which migrated content lands where
• docs/methodology/session-safety.md — migration scripts are state-mutating; will use worktree pattern
• docs/methodology/planning-docs.md — spec/design conventions
• Memory: feedback_artifact_language — English-only artifacts
• Memory: project_consumption_model (superseded) — original consumption plan; some references to Confluence pages in there will rot post-migration

---

Triage notes

Filled in during triage. Empty until then.

Reviewed: TBD Decision: TBD — proposed phasing: 1 → 4 → 2 → 3 → 5 (de-dup must happen before any cluster migration; Phase 4 unblocks 2 and 3) Owner: @relbns (or hand off if a teammate volunteers) ClickUp: TBD