Metadata-Version: 2.4
Name: piagentsync
Version: 0.0.3rc2
Summary: Sync OpenCode agents and skills from an Obsidian vault to workspace directories
License: MIT
License-File: LICENSE
Requires-Python: >=3.13
Requires-Dist: pydantic-settings>=2.3
Requires-Dist: pydantic>=2.7
Requires-Dist: python-frontmatter>=1.1
Requires-Dist: rich>=13
Requires-Dist: typer>=0.12
Description-Content-Type: text/markdown

# piagentsync

Sync OpenCode agents and skills from an Obsidian vault to workspace directories.

## Install

```bash
uv add piagentsync
# or
pip install piagentsync
```

## Quick start

1. Initialize a new project in your vault:

```bash
piagentsync init myproject --workspace ~/workspace/myproject
```

2. Pull the synced files to your workspace:

```bash
piagentsync pull myproject
```

## Configuration

Environment variables (also configurable via `.env` file):

| Variable | Default | Description |
|----------|---------|-------------|
| `PIAGENTSYNC_VAULT_PATH` | `~/vault` | Path to Obsidian vault |
| `PIAGENTSYNC_GLOBAL_OPENCODE_PATH` | `~/.config/opencode` | Path to global OpenCode config |

## CLI reference

### `piagentsync pull <project>`

Sync a single project from vault to workspace.

Options:
- `--dry-run` / `--no-dry-run` — preview changes without writing
- `--global` / `--no-global` — also sync global agents
- `--all` — sync all discovered projects

### `piagentsync status [project]`

Show diff between vault and workspace.

Options:
- `--all` — show status for all projects (default when no project given)

### `piagentsync init <project>`

Scaffold a new project in the vault.

Options:
- `--workspace PATH` — required, workspace directory
- `--notion-board-id TEXT` — optional Notion DB ID
- `--notion-project-filter TEXT` — optional Notion project filter (defaults to project slug)

### `--version`

Print version and exit.

## AGENTS.md manifest format

Each project must have an `AGENTS.md` file in its root with YAML frontmatter:

```yaml
---
project: myproject
workspace: ~/workspace/myproject
notion_board_id: 3305f9479a8d8055b3c3e86a9006cf91
notion_project_filter: myproject
---
```

The body below the frontmatter is the OpenCode routing table.

## Expected vault structure

```
vault/
├── agents/
│   └── global/
│       └── *.md
└── projects/
    └── {project}/
        ├── AGENTS.md           # manifest with frontmatter
        ├── context.md          # optional context file
        ├── decisions.md        # optional decisions log
        ├── agents/
        │   └── *.md
        └── skills/
            └── *.md
```

## Contributing

Development setup:

```bash
uv sync
uv run pytest
```

Lint and format:

```bash
uv run ruff check src/ tests/
uv run ruff format src/ tests/
```

All commits follow [Conventional Commits](https://www.conventionalcommits.org/).

### Publishing (maintainers)

This repository uses GitHub Actions for CI and automated releases.

#### One-time PyPI setup (trusted publisher)

1. Enable OIDC on PyPI for the repository:
   - Publisher: GitHub Actions
   - Repository owner: `Piwero`
   - Repository name: `piagentsync`
   - Workflow filename: `release.yml`
   - Environment name: (leave blank)

2. The Release workflow handles everything: bump version, create tag, build, publish to PyPI, and create a GitHub Release.

#### Release process

```text
git push → ci.yml passes
   → trigger release.yml (choose MAJOR/MINOR/PATCH/RC)
       → tests re-run → changelog generated → version bumped → tag pushed
       → GitHub Release created with assets → package published to PyPI
```

## License

MIT
