svgn 0.2.0

Two-way sync between Linear/Notion and local Markdown files — Docs-as-Code for developers

Sovereign Sync (svgn)

svgn is a professional developer utility that synchronizes your Linear backlog and Notion documentation with local Markdown files. It enables a "Docs-as-Code" and "Dev-as-Code" workflow, allowing you to manage project execution and technical specifications directly from your code editor.

---

📂 Project Structure

The codebase is organized into a modular package for scalability and reliability:

src/svgn/
├── api/             # Low-level API wrappers for Linear & Notion
├── engines/         # Sync logic and state management
├── utils/           # Markdown parsing and Notion block conversion
└── main.py          # CLI Entry point

---

🛠 Command Reference

1. Core Lifecycle Commands

svgn init

Run this first.

• Discovers Linear teams and sets your Team ID if not provided.
• Automatically detects Notion credentials if present in .env.
• Creates linear_tickets/ and docs/ directories.

---

svgn sync

Linear Master Pull.

• Fetches all active tickets from Linear and populates your local folders.
• Updates local "fingerprints" to ensure subsequent updates are efficient.

svgn update

Local ➡ Linear.

• Scans linear_tickets/ for local changes (status moves or text edits).
• Pushes changes to Linear. Uses .svgn_state to skip unchanged files.

---

2. Documentation (Notion) Commands

svgn docs sync

Notion ➡ Local.

• Downloads your Notion root page and all sub-pages as Markdown files into the docs/ folder.
• Converts Notion blocks (headings, code, lists) into clean local Markdown.

svgn docs update

Local ➡ Notion.

• Detects edits in your docs/ folder.
• Clears the corresponding Notion page and re-uploads the fresh Markdown content as blocks.
• Note: Only modifies pages that have changed locally.

---

3. Utility Commands

svgn inspect

• Prints valid Assignee Emails, Labels, and Projects from Linear. Use this to ensure your Markdown frontmatter is accurate.

svgn logs

• Displays a timestamped history of local-to-remote sync operations.

---

📋 Full Setup Workflow

1. Install: Run uv pip install -e . (or pip install -e .) from the root directory.
2. Environment: Ensure your .env contains the following :

   LINEAR_API_KEY=...
   LINEAR_TEAM_ID=...
   NOTION_TOKEN=...
   NOTION_ROOT_PAGE_ID=...
   

3. Notion Permission: Open your Notion page, click ... -> Connect to -> and select your Integration.
   • Each page should be given access explicitly in the integrations.
4. Initialize:

   svgn init
   svgn sync        # Pull tickets from Linear
   svgn docs sync   # Pull documentation
   

---

🧠 Using with AI (Cursor / Copilot)

The generated .cursorrules file instructs AI agents to respect the svgn workflow.

Example Prompts:

Planning with Docs:

"Read @architecture.md from the docs folder and create three implementation tasks in the todo folder. Assign them to me and run svgn update."

Executing a Task:

"Help me implement the logic described in @setup-database-migration.md. Once done, move the file to the done folder and run svgn sync."

---

📄 Metadata Examples

Linear Ticket (linear_tickets/todo/task.md)

---
linear_id: "uuid"
title: "Fix Auth Bug"
assignee: "[e-mail]"
labels: ["bug", "security"]
priority: "urgent"
---
## Description
...

Notion Document (docs/api-spec.md)

---
notion_id: "uuid"
title: "API Specification v2"
---
# API v2
This document tracks our REST endpoints...

---

🛠 Troubleshooting

• 400 Bad Request (Notion): Ensure you have duplicated the Notion page to your private workspace and added the "Connection" via the page settings.
• Sync Loops: svgn uses .svgn_state and .svgn_docs_state to store fingerprints. If a file is reverting unexpectedly, run svgn pull or svgn docs sync to refresh the local state.