Import existing design docs

Most teams arrive with a folder of RFCs in a repository, a Notion database of design pages, or both. Importing them makes search, engineering context and "Used in" useful before anyone writes a new document.

Imported documents are history, not drafts. Each one lands in its final status (Shipped unless the source says otherwise) with its original date, author and identifier, a link back to where it came from, and an Imported badge. The original identifier, such as RFC-042, shows beside the Archdocs number and is searchable. Review, approvals and notifications are skipped. Importing needs the Team plan or above.

Import from the app

Open My docs, filter to design docs, and choose New > Import design docs. Pick a source.

Files

Drop markdown files or choose a folder. Archdocs reads the title, date, author and identifier from frontmatter, the first heading and the filename, and pairs a spec with its plan when the names match (2026-03-04-billing-design.md and 2026-03-04-billing-plan.md).

Notion export

In Notion, export the page or database as Markdown and CSV and upload the zip. Status, created date and owner come from the page properties or the database CSV. Images come along as attachments.

GitHub

Pick a repository the Archdocs GitHub App can see and a path pattern such as docs/rfcs/**/*.md. Files are read from the default branch, with the date of their last commit.

Every source lands in the same preview table. Fix a title, change a status or date, untick what you do not want, then confirm. Nothing is written until you do. Each imported document gets a link in the results.

With ArchDocs AI enabled, Suggest with AI fills in titles, statuses, dates and authors it can read from the text and pairs related files. It never changes a field you edited. The Split setting splits a single document into a spec and a plan by its headings; review the split per row before importing. AI never rewrites your text.

Import with your agent

The Archdocs plugin for Claude Code, Codex and Cursor includes an importing-design-docs skill, also available as /archdocs:import-docs. The agent scans a folder, repository or export, classifies each file, pairs specs with plans, reads dates and authors from git, and shows you a mapping table with every guess marked. After you approve it, the agent imports each document with the import_design_doc tool and decision records with create_adr in historical mode, then reports what landed and what it skipped.

Re-running an import

An import is matched by its original identifier, or by its source URL when there is none. Running it again with the same identifier updates the document in place and adds a version instead of creating a duplicate, so fixing a wrong title or status is a re-import.

What is not imported

Approvals, review threads and evidence from the old system are not reconstructed. Pages people are still editing elsewhere should be imported as Draft, or left where they live until they are done.