Reorganize Documents

Reorganize Documents

This page lives in 9 Archive/ (meta / housekeeping). The main entry point is still the site home (Team documentation).

Migration status

Done: All markdown sources from docs/OLD-DOCS/ were moved into docs/src/content/docs/ using the category folders below. See docs/OLD-DOCS/README.md for the pointer to this tree. Content was not summarized or dropped—only paths changed.

Audience

These docs live in the same Starlight site as other content, but they are for the team only (implementation history, runbooks, research). Customers do not use this docs site as a product surface—organization and naming should help developers and operators. There is no requirement for a parent folder named internal.

---

Goal

Create a clear folder layout under:

• docs/src/content/docs

so teammates can find work by product area (data pipeline, billing, admin UI, chat, ops, etc.)—not by historical “phase” numbers.

Implemented: The layout below is live under docs/src/content/docs/. docs/OLD-DOCS/ now only holds README.md as a pointer; you may delete that folder after updating bookmarks.

---

How to think about the former “Option A — Phase …” plans

Those docs were planning bundles (historically named Option-A-Phase-*.md): each often covers several features. They are not a folder structure.

Current state: Files use descriptive slugs (e.g. billing-and-usage.md, rag-and-chat-api.md) and titles without the Option A — Phase … prefix. Bodies may still mention “Phase N” where useful for sequencing.

When adding or moving docs:

• Do not create a phases/ folder or sort only by old phase order.
• Do place each file under the category that matches its primary subject (see mapping below).

---

Principles

• Team-first clarity: folders describe what the system area is, not delivery phase.
• One source of truth per topic where possible.
• Separate by domain (team documentation & product direction, platform, knowledge/RAG, billing, admin product, chat, ops, research).
• Optional frontmatter (status, lastReviewed, legacySource) where useful.
• New docs go under docs/src/content/docs/<category folder>/ (category folders use spaces in the name, e.g. 01 Platform Foundation).

---

Proposed Folder Structure (Target)

All paths are under docs/src/content/docs/. There is no phases folder.

Folder	What belongs here
00 Team documentation/	Product direction, architecture options, tech stack checklist; linked from the site home (index.mdx — Team documentation).
01 Platform Foundation/	App shell, prerequisites, OAuth/session/webhooks baseline, environment setup—work that everything else sits on.
02 Knowledge and RAG/	Database/schema for vectors, product sync & ingestion, chat API + retrieval, extended catalog sync, website knowledge, call-stack / pipeline docs.
03 Billing and Usage/	Subscriptions, usage metering, credits, free-plan limits, Shopify billing mechanics, billing follow-up tasks.
04 Admin and Storefront/	Merchant admin settings, embedded app UX, storefront widget, dashboard, AI chat logs, design system / theme for admin, billing screen layout.
05 Chat Experience and Safety/	Guardrails, order-status conversational flows, conversation memory/context, pre-chat identity—anything about what the chat does for the shopper.
06 Merchant Lifecycle/	Identifying or tracking merchant/staff users, install/register flows, uninstall flows and comms.
07 Ops and Release/	Launch checklist, deployment (e.g. tunnel/hosting), testing runbooks, operational URLs (after cleanup).
08 Research and Ideas/	Competitors, marketing drafts, naming, template shortlists, monetization gap roadmaps, broad ideation.
9 Archive/	Placeholders, superseded copies, raw link dumps, and this folder map (ReorganizeDocuments.md).

---

Mapping: plan doc → category

Each row is one primary home; cross-link from index.mdx or a small index if a doc touches two areas.

File	Primary category
prerequisites.md	01 Platform Foundation/
shopify-app-skeleton-and-database.md	01 Platform Foundation/
database-schema-for-rag.md	02 Knowledge and RAG/
product-sync-and-ingestion.md	02 Knowledge and RAG/
rag-and-chat-api.md	02 Knowledge and RAG/
admin-settings-and-chat-widget.md	04 Admin and Storefront/
billing-and-usage.md	03 Billing and Usage/
billing-remaining-tasks.md	03 Billing and Usage/
launch-and-publishing-guide.md	07 Ops and Release/
deploy-cloudflare-tunnel-and-appifire-ai-chat.md	07 Ops and Release/
ai-chats-logs.md	04 Admin and Storefront/
theme-and-design-system.md	04 Admin and Storefront/
register-users.md	06 Merchant Lifecycle/
uninstall-users.md	06 Merchant Lifecycle/
rag-data-sync.md	02 Knowledge and RAG/
website-knowledge-from-web.md	02 Knowledge and RAG/
dashboard-plan.md	04 Admin and Storefront/
admin-ui-design-plan.md	04 Admin and Storefront/
order-status-chat-flow.md	05 Chat Experience and Safety/
conversation-history-context.md	05 Chat Experience and Safety/
pre-chat-user-identity-form.md	05 Chat Experience and Safety/

---

Current Document Status Classification

Implemented (team reference / shipped behavior)

Implementation / delivery plans (treat as team record; each may bundle multiple features):

• All slug files in the mapping table above (prerequisites.md, billing-and-usage.md, etc.).

Other implementation / verification docs:

• Chat-Guardrails-Inspection.md → 05 Chat Experience and Safety/
• Testing-up-to-Phase-2.md → 07 Ops and Release/
• Vector-RAG-Chat-Call-Stack.md → 02 Knowledge and RAG/

Planning (roadmaps, guidelines, follow-on work)

• Billing-Screen-Restructure-Plan.md → 04 Admin and Storefront/
• Chat-Paid-Feature-Gaps-Roadmap.md → 08 Research and Ideas/ (or 05-… if you prefer product-only—default: research)
• Design-Guidelines-and-Styling-System.md → 04 Admin and Storefront/
• Free-Plan-Credits.md → 03 Billing and Usage/
• TechStackAndHighLevelTasks.md → 00 Team documentation/
• ShopifyAiChatbotPlanOptions.md → 00 Team documentation/
• Shopify-App-Billing-and-Payments.md → 03 Billing and Usage/
• index.mdx → team home remains docs/src/content/docs/index.mdx (title Team documentation); optional per-section index under 00 Team documentation/index.mdx
• my-rnd/Marketing Plan.md → 08 Research and Ideas/
• my-rnd/SetupShopifyAndApp.md → 01 Platform Foundation/ or 07 Ops and Release/ (partner setup → often 01 Platform Foundation/)
• my-rnd/readme.md → 00 Team documentation/ or 08 Research and Ideas/ after deduping

Idea

• Top-30-Shopify-App-Ideas.md, app-names.md, tasks.md, templates-shortlisted.md, my-rnd/AI Chat Bot Comparions.md, my-rnd/Docs & Competitors.md → 08 Research and Ideas/

Unknown / Archive candidate

• future-todo-list.md, raw links.md → 9 Archive/ or merge links.md into 07 Ops and Release/
• ReorganizeDocuments.md → 9 Archive/ (this file)

---

Migration Plan (Execution Steps)

1. Category folders already exist under docs/src/content/docs/ (no phases/ folder).
2. New docs: place under one primary category using the mapping table.
3. Prefer descriptive filenames (no Option-A-Phase-XX- prefix).
4. Optional: short index.mdx per category listing child docs + links to related categories.
5. Consolidate duplicate “master” narratives in 00 Team documentation/.
6. Remove docs/OLD-DOCS/ when the team no longer needs the pointer README.md.

---

Rules For All New Documents

• Add new docs under the category that matches the feature or system area—not a phase number.
• Prefer titles like “Billing: usage metering” over “Phase 5”.
• Optional frontmatter: status, lastReviewed, legacySource.

---

Suggested Index Files

One index per top-level folder, e.g.:

• 00 Team documentation/index.mdx (optional per-folder index)
• 01 Platform Foundation/index.mdx
• 02 Knowledge and RAG/index.mdx
• 03 Billing and Usage/index.mdx
• 04 Admin and Storefront/index.mdx
• 05 Chat Experience and Safety/index.mdx
• 06 Merchant Lifecycle/index.mdx
• 07 Ops and Release/index.mdx
• 08 Research and Ideas/index.mdx
• 9 Archive/index.mdx