# How /notion‑sync Creates a Read‑Only Pipeline View in Notion

> Learn how /notion-sync creates a read-only pipeline view in Notion. Export your job search status to Notion as the single source of truth without uploading documents.

- Repository: [Mads Lorentzen/ai-job-search](https://github.com/MadsLorentzen/ai-job-search)
- Tags: how-to-guide
- Published: 2026-08-05

---

**/notion‑sync** is a one‑way publishing command that exports your job‑search pipeline state to a Notion database without uploading any document contents, keeping the repository as the single source of truth.

The `ai-job-search` repository developed by MadsLorentzen provides a suite of Claude Code commands for managing AI‑assisted job applications. Among these, `/notion‑sync` serves a specific purpose: it creates a **glanceable, always‑up‑to‑date view** of your ranked jobs and tracked applications that you can access from any device running Notion. This article explains the architecture, setup steps, and privacy guarantees behind this read‑only pipeline view.

## One‑Way Data Flow Architecture

The `/notion‑sync` command implements a **strictly unidirectional** data pipeline. Understanding this architecture is key to using the feature correctly.

### Data Sources and Aggregation

The command aggregates data from two internal sources:

- **Ranked job list** — produced by the `/rank` command and stored in [`tracker.json`](https://github.com/MadsLorentzen/ai-job-search/blob/main/tracker.json)
- **Tracked applications** — produced by `/apply` and `/outcome` commands

According to the deduplication logic referenced in [`.claude/skills/upskill/SKILL.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.claude/skills/upskill/SKILL.md) at line 57, jobs that appear in both the ranked list and the applications list are merged into a single row. This prevents duplicate entries for positions you have already applied to.

### What Gets Synced (and What Doesn't)

The sync includes only **metadata fields**:

| Synced | Excluded |
|--------|----------|
| Job titles | Résumé contents |
| Company names | Cover letter contents |
| Role descriptions | Any other document files |
| URLs | — |
| Application status | — |

As documented in [`SECURITY.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/SECURITY.md) at line 15, this selective sync respects privacy guarantees by ensuring no personal document contents leave your local repository. The repository remains the **authoritative data store**.

## Notion MCP Integration Setup

The command relies on the official **Notion MCP (Managed Cloud Platform) server** for authentication and API access.

### Prerequisites

Before running `/notion‑sync`, you must complete a one‑time OAuth configuration:

```bash

# Step 1: Add the Notion transport (run once per environment)

claude mcp add --transport http notion https://mcp.notion.com/mcp

# Step 2: Restart your Claude session to pick up the new server

claude session start

# Step 3: Complete OAuth authentication inside the session

/mcp

```

The command specification in [`.claude/commands/notion-sync.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.claude/commands/notion-sync.md) at line 31 explicitly warns: *"Notion MCP isn't connected. Run `claude mcp add …` then re‑run `/notion‑sync`"* if this setup is incomplete.

### Executing the Sync

Once authenticated, trigger the sync with a single command:

```bash
/notion-sync

```

This reads the current [`tracker.json`](https://github.com/MadsLorentzen/ai-job-search/blob/main/tracker.json) state, applies deduplication, and pushes rows to your configured Notion database.

## Row Structure and Read‑Only Semantics

Each job or application becomes **one row** in the target Notion database with the following characteristics:

- **Write‑once briefing page** — Attached to each row, containing a snapshot of key details
- **Repository backlinks** — Links point back to the corresponding files in your local repo
- **No edit capability** — The Notion side has no connection back to the repository; any desired changes must be made locally and then re‑synced

This design creates the **read‑only pipeline view**: Notion serves as a display layer while all state management happens in the repository.

## Comparison with /html‑report

The `/notion‑sync` command complements rather than replaces the offline reporting lane:

| Feature | `/notion‑sync` | `/html-report` |
|--------|---------------|----------------|
| **Access** | Any device with Notion (desktop, web, mobile) | Local machine only |
| **Update mechanism** | Re‑run command to refresh | Re‑run command to regenerate |
| **Interactivity** | Read‑only, glanceable | Detailed, filterable dashboard |
| **Network requirement** | Requires Notion MCP connection | Fully offline |

As noted in [`.claude/commands/notion-sync.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.claude/commands/notion-sync.md) at line 9, `/notion‑sync` prioritizes **ubiquitous access** while `/html-report` prioritizes **rich local analysis**.

## Security and Privacy Guarantees

The feature implements defense‑in‑depth privacy controls:

1. **Filename‑only sync** — Document paths are referenced, never uploaded
2. **OAuth‑scoped permissions** — Uses standard Notion MCP authorization flows
3. **No bidirectional sync** — Eliminates risk of external modifications propagating to your repository

These constraints are intentional design decisions documented across [`SECURITY.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/SECURITY.md) and the command specification.

## Summary

- **/notion‑sync** creates a one‑way, read‑only view of your job‑search pipeline in Notion
- Only job metadata (titles, companies, URLs, status) is synced—no document contents
- Requires one‑time Notion MCP setup via `claude mcp add` and OAuth flow
- Each row includes a briefing page with backlinks to repository files
- Changes must be made locally and re‑synced; Notion remains a display layer
- Complements the offline `/html-report` with cross‑device accessibility

## Frequently Asked Questions

### What happens if I edit data directly in Notion?

Any changes made directly in Notion are **not synchronized back** to your repository. The next time you run `/notion‑sync`, those edits will be overwritten with the current repository state. To make persistent changes, update your local tracker files and re‑run the command.

### Can I sync to multiple Notion workspaces?

The current implementation supports **one Notion MCP connection** per Claude environment. To target a different workspace, you would need to reconfigure the transport with `claude mcp add` using credentials for that workspace, then restart your session.

### Why are my documents not appearing in Notion?

By design, `/notion‑sync` **never uploads document contents**. Only filenames and metadata are transmitted. If you need to review full résumés or cover letters, use the repository directly or the local `/html-report` output. Refer to [`SECURITY.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/SECURITY.md) line 15 for the privacy rationale.

### How do I update the Notion view after applying to new jobs?

Run `/notion-sync` again after any repository changes—such as running `/rank`, `/apply`, or `/outcome`. The command performs deduplication automatically and refreshes all rows to reflect the current pipeline state.