halyard 0.0.1__tar.gz

halyard-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint with ruff
+        run: ruff check .
+
+      - name: Format check with ruff
+        run: ruff format --check .
+
+      - name: Type-check with mypy
+        run: mypy src
+
+      - name: Test with pytest
+        run: pytest --cov=halyard --cov-report=term-missing

halyard-0.0.1/.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+.eggs/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Environments
+.venv/
+venv/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+.DS_Store
+
+# Halyard runtime
+.halyard-cache/
+.halyard/active
+
+# OS
+Thumbs.db

halyard-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kormilo LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

halyard-0.0.1/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: halyard
+Version: 0.0.1
+Summary: Plain-text, agent-native financial OS for freelancers.
+Project-URL: Homepage, https://github.com/Kormiloio/Halyard
+Project-URL: Repository, https://github.com/Kormiloio/Halyard
+Project-URL: Issues, https://github.com/Kormiloio/Halyard/issues
+Author: Kormilo LLC
+License: MIT
+License-File: LICENSE
+Keywords: accounting,agent,claude,freelance,invoicing,plaintext,time-tracking
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial :: Accounting
+Requires-Python: >=3.11
+Requires-Dist: anthropic>=0.40
+Requires-Dist: dateparser>=1.2
+Requires-Dist: jinja2>=3.1
+Requires-Dist: pydantic>=2.6
+Requires-Dist: rich>=13.7
+Requires-Dist: tomli-w>=1.0
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Halyard
+
+> *A halyard is the line that raises the sails. Pull on it, the sails go up. Pull on this one, your books go up.*
+
+A plain-text, agent-native financial OS for freelancers. Your time, expenses, and invoices live as plain text on your laptop. An AI agent (Claude) reads and writes them on your behalf.
+
+**Status:** pre-alpha. v0 in development. Watch the repo for the first release.
+
+## The pitch
+
+You run a freelance business. Your time tracking is in Notion or Toggl. Your invoices are in FreshBooks or QuickBooks. Your expenses are CSVs you've been meaning to deal with. Your data is locked in five different SaaS subscriptions, none of which talk to each other, all of which get more expensive every year.
+
+Halyard is an alternative:
+
+- **Local-first.** Everything lives in a folder on your computer. Git it, back it up, sync it however you want.
+- **Plain text forever.** [hledger timeclock](https://hledger.org/timeclock.html) for time, [Beancount](https://beancount.github.io/) for ledgers, markdown for invoices. No proprietary formats. Compatible with the entire plaintext-accounting ecosystem on day one.
+- **Agent-native.** "I worked 3 hours on ACME this morning" → entry written. "Draft an invoice for last month" → markdown + PDF generated. The agent edits the same files you can edit by hand.
+- **Open source, MIT.** Yours forever.
+
+## Quickstart
+
+> Coming with v0.1.0. See [`openspec/changes/v0-time-and-invoice/`](./openspec/changes/v0-time-and-invoice/) for what's being built.
+
+```bash
+pipx install halyard
+cd ~/businesses/my-freelance
+halyard init
+halyard
+```
+
+## How it's being built
+
+This project uses [OpenSpec](https://github.com/Fission-AI/OpenSpec) for spec-driven development. Every feature lives as a change folder under `openspec/changes/` with a proposal, specs, design, and tasks.
+
+To see what's being built next, look at any folder under `openspec/changes/` that hasn't been moved to `openspec/changes/archive/`.
+
+## Roadmap
+
+- **v0** — time tracking + invoicing CLI + Claude REPL. *In progress.*
+- **v1** — expense ingestion, local web UI at `localhost:7474`, plugin/skill system.
+- **v2** — bank sync (Plaid), full bookkeeping automation, project profitability.
+- **v3+** — tax forms, e-file. Distant future.
+
+## Contributing
+
+Too early. Star the repo and watch for v0.1.0.
+
+## License
+
+MIT.
+
+---
+
+A [Kormilo LLC](https://kormilo.io) project. *Kormilo* is Slavic for "rudder" — the helm of your business. Halyard is the first thing it builds.

halyard-0.0.1/README.md

@@ -0,0 +1,54 @@
+# Halyard
+
+> *A halyard is the line that raises the sails. Pull on it, the sails go up. Pull on this one, your books go up.*
+
+A plain-text, agent-native financial OS for freelancers. Your time, expenses, and invoices live as plain text on your laptop. An AI agent (Claude) reads and writes them on your behalf.
+
+**Status:** pre-alpha. v0 in development. Watch the repo for the first release.
+
+## The pitch
+
+You run a freelance business. Your time tracking is in Notion or Toggl. Your invoices are in FreshBooks or QuickBooks. Your expenses are CSVs you've been meaning to deal with. Your data is locked in five different SaaS subscriptions, none of which talk to each other, all of which get more expensive every year.
+
+Halyard is an alternative:
+
+- **Local-first.** Everything lives in a folder on your computer. Git it, back it up, sync it however you want.
+- **Plain text forever.** [hledger timeclock](https://hledger.org/timeclock.html) for time, [Beancount](https://beancount.github.io/) for ledgers, markdown for invoices. No proprietary formats. Compatible with the entire plaintext-accounting ecosystem on day one.
+- **Agent-native.** "I worked 3 hours on ACME this morning" → entry written. "Draft an invoice for last month" → markdown + PDF generated. The agent edits the same files you can edit by hand.
+- **Open source, MIT.** Yours forever.
+
+## Quickstart
+
+> Coming with v0.1.0. See [`openspec/changes/v0-time-and-invoice/`](./openspec/changes/v0-time-and-invoice/) for what's being built.
+
+```bash
+pipx install halyard
+cd ~/businesses/my-freelance
+halyard init
+halyard
+```
+
+## How it's being built
+
+This project uses [OpenSpec](https://github.com/Fission-AI/OpenSpec) for spec-driven development. Every feature lives as a change folder under `openspec/changes/` with a proposal, specs, design, and tasks.
+
+To see what's being built next, look at any folder under `openspec/changes/` that hasn't been moved to `openspec/changes/archive/`.
+
+## Roadmap
+
+- **v0** — time tracking + invoicing CLI + Claude REPL. *In progress.*
+- **v1** — expense ingestion, local web UI at `localhost:7474`, plugin/skill system.
+- **v2** — bank sync (Plaid), full bookkeeping automation, project profitability.
+- **v3+** — tax forms, e-file. Distant future.
+
+## Contributing
+
+Too early. Star the repo and watch for v0.1.0.
+
+## License
+
+MIT.
+
+---
+
+A [Kormilo LLC](https://kormilo.io) project. *Kormilo* is Slavic for "rudder" — the helm of your business. Halyard is the first thing it builds.

halyard-0.0.1/openspec/changes/v0-time-and-invoice/design.md

@@ -0,0 +1,120 @@
+# Design
+
+## Stack
+
+- **Language:** Python 3.11+ (Typer for CLI, Rich for terminal output)
+- **Agent:** Anthropic SDK direct, single-turn tool-use loop
+- **Models:** Pydantic v2 for config schemas
+- **Templating:** Jinja2
+- **PDF:** typst via subprocess (cleaner output than weasyprint, single binary)
+- **Time parsing:** dateparser
+- **Tests:** pytest, with golden-file tests for invoice rendering
+
+### Why Python?
+
+Largest contributor pool for AI tooling, easy install via `pipx`, fast
+iteration. We can rewrite hot paths or distribute as a Rust binary later
+if real performance demands it. Day-one priority is contributor velocity,
+not microbenchmark wins.
+
+### Why typst over weasyprint?
+
+typst produces consistently good-looking PDFs out of the box, compiles in
+milliseconds, and has a clean templating language that we can expose to
+power users later as an alternative invoice format. weasyprint requires
+HTML+CSS to look professional, and the output quality varies. typst is a
+single static binary the installer can fetch.
+
+### Why no Beancount in v0?
+
+Beancount makes the project look like an accounting tool, not a freelancer
+tool. v0's audience is "freelancer who wants to log time and send invoices."
+The double-entry ledger lands in v1 alongside expenses, which is when
+double-entry actually pulls its weight.
+
+## Agent loop
+
+Single-turn tool-using loop, not multi-turn autonomy in v0.
+
+A user message comes in. Claude is given the system prompt + the message +
+the current tools. Claude either responds with text or proposes one or more
+tool calls. Tool calls are executed (with approval for writes). The result
+is fed back to Claude, which either calls more tools or produces a final
+text response. Then we wait for the next user message.
+
+We are explicitly NOT building an autonomous loop in v0. Every user
+interaction is initiated by the user. No background work. No daemons.
+
+### Tools exposed to Claude
+
+```
+read_text(path: str) -> str
+    Read any file under the project root. No approval needed.
+
+list_clients() -> list[Client]
+    Read clients.toml and return parsed entries. No approval needed.
+
+list_projects() -> list[Project]
+    Read projects.toml and return parsed entries. No approval needed.
+
+run_hledger(args: list[str]) -> str
+    Run hledger with the project's time.timeclock as -f. Read-only.
+
+append_timeclock(entries: list[TimeclockEntry]) -> None
+    APPROVAL REQUIRED. Append timeclock entries to time.timeclock.
+
+render_invoice(client_slug: str, period: Period, line_items: list[LineItem]) -> Path
+    APPROVAL REQUIRED. Generate the invoice .md and .pdf, increment counter.
+
+upsert_client(client: Client) -> None
+    APPROVAL REQUIRED. Add or update a client in clients.toml.
+
+upsert_project(project: Project) -> None
+    APPROVAL REQUIRED. Add or update a project in projects.toml.
+```
+
+### Approval UX
+
+When Claude proposes a write, the CLI:
+
+1. Prints the human-readable diff (Rich-rendered).
+2. Prompts: `Apply? [y/N/edit]` — `edit` opens `$EDITOR` on a temp file
+   containing the proposed change so the user can tweak before applying.
+3. On `y`, applies the change and returns success to the agent.
+4. On `N`, returns a tool error like "User declined the change" so the
+   agent can react conversationally.
+
+## System prompt
+
+Loaded from `prompts/system.md`, version-controlled in the repo. It
+establishes:
+
+- Halyard's role and constraints.
+- The file layout and formats it can rely on.
+- Formatting rules for timeclock entries.
+- Escalation behavior (when in doubt, ask; never invent a slug).
+- Tone (concise, direct, terminal-native).
+
+## Out-of-scope clarification
+
+No async, no daemons, no LSP, no extension points in v0. Each command is a
+fresh process; state lives entirely in files. The only persistent runtime
+state is `~/.halyard/active` (the active timer), which is a single line of
+text.
+
+## Testing strategy
+
+- Unit tests for parsers (timeclock round-trip, TOML schema validation).
+- Golden-file tests for the default invoice template — render a fixed input
+  and diff against a checked-in expected output.
+- A small integration test using Anthropic's prompt-caching test endpoint
+  is **out of scope** for v0; we mock the agent layer in unit tests and
+  exercise the real model only manually until v1.
+
+## Open questions (resolve before implementation)
+
+1. Default currency formatting: rely on Babel, or hard-code USD/EUR/GBP for v0?
+2. typst install: bundle as a Python package dep, ship a small downloader
+   script in `halyard init`, or instruct users to install separately?
+3. API key handling: env var only (`ANTHROPIC_API_KEY`), or also a
+   `~/.halyard/config.toml` entry? Env var only is simpler and safer.

halyard-0.0.1/openspec/changes/v0-time-and-invoice/proposal.md

@@ -0,0 +1,35 @@
+# v0: Time tracking and invoice drafting
+
+## Why
+
+Freelancers waste hours every month on the same loop: scattered time notes,
+chasing invoice templates, fighting accounting software they hate. Existing
+tools (FreshBooks, QuickBooks, Harvest) are SaaS, lock data in proprietary
+databases, and have nothing meaningful in the way of an AI agent.
+
+We're building the smallest version of Halyard that can demo the full thesis
+in 60 seconds: log time in natural language, generate an invoice from those
+hours, and prove the data is just plain text the user owns.
+
+The deliverable for v0 is *the demo video*, not the binary. The binary exists
+to make the video true.
+
+## What's changing
+
+- New CLI binary `halyard` with `init`, `log`, `start`, `stop`, `invoice`,
+  and an interactive REPL that drops you into a Claude-powered session.
+- New project layout: `halyard.toml`, `clients.toml`, `projects.toml`,
+  `time.timeclock`, `invoices/`.
+- Default markdown invoice template + typst PDF renderer.
+- Single-turn agent loop with three tools: `read_text`, `append_timeclock`,
+  `render_invoice`. Plus `run_hledger` for read-only queries. All writes
+  require user approval.
+
+## Out of scope (v0)
+
+- Expenses, bank sync, reconciliation → v1
+- Local web UI → v1
+- Plugin/skill system → v1
+- Beancount ledger → v1
+- Tax forms, e-file → v3+
+- Multi-currency edge cases → v2

halyard-0.0.1/openspec/changes/v0-time-and-invoice/specs/cli.md

@@ -0,0 +1,116 @@
+# CLI Spec
+
+## Requirement: halyard init
+
+The CLI MUST scaffold a new Halyard project in the current directory.
+
+### Scenario: first-time setup
+
+- WHEN the user runs `halyard init` in an empty directory
+- THEN the CLI creates `halyard.toml`, `clients.toml`, `projects.toml`,
+  `time.timeclock`, `invoices/`, and `.gitignore`
+- AND prints a welcome message with three suggested next commands
+
+### Scenario: existing Halyard project
+
+- WHEN the user runs `halyard init` in a directory containing `halyard.toml`
+- THEN the CLI exits with code 1
+- AND prints a message instructing the user to remove or move the existing
+  project before re-initializing
+
+## Requirement: halyard log (natural language)
+
+The CLI MUST accept a free-form string and use Claude to extract a
+timeclock entry.
+
+### Scenario: simple past-tense log
+
+- WHEN the user runs `halyard log "worked 3h on ACME auth migration this morning"`
+- THEN Claude extracts client=acme, project=auth-migration, duration=3h,
+  start=this morning (resolved against the current local date)
+- AND the CLI displays the proposed timeclock lines and prompts for confirmation
+- AND on confirmation, appends them to `time.timeclock`
+
+### Scenario: ambiguous client
+
+- WHEN the user logs time against a client name not present in `clients.toml`
+- THEN Claude proposes adding the client
+- AND asks for the hourly rate before logging the time entry
+
+### Scenario: declined confirmation
+
+- WHEN the user is prompted to confirm a proposed entry and declines
+- THEN no files are written
+- AND the CLI exits cleanly with code 0
+
+## Requirement: halyard start / stop
+
+The CLI MUST support live timing.
+
+### Scenario: start a timer
+
+- WHEN the user runs `halyard start acme/auth-migration`
+- THEN the CLI writes an `i` line to `time.timeclock` with the current
+  timestamp and the slug `acme:auth-migration`
+- AND records the active timer in `~/.halyard/active`
+
+### Scenario: stop the active timer
+
+- WHEN the user runs `halyard stop` and a timer is active
+- THEN the CLI writes an `o` line to `time.timeclock` with the current timestamp
+- AND clears the active timer file
+
+### Scenario: stop with no active timer
+
+- WHEN the user runs `halyard stop` and no timer is active
+- THEN the CLI exits with code 1 and a clear message
+
+## Requirement: halyard invoice
+
+The CLI MUST generate invoices from time entries for a client and date range.
+
+### Scenario: invoice last month for a client
+
+- WHEN the user runs `halyard invoice acme --month last`
+- THEN the CLI reads `time.timeclock`, sums hours by project for ACME in
+  the prior calendar month
+- AND applies hourly rates from `clients.toml` (with project-level overrides
+  from `projects.toml` taking precedence)
+- AND generates `invoices/2026-04-acme-001.md` and the corresponding `.pdf`
+- AND increments the invoice counter in `halyard.toml`
+- AND opens the PDF using the platform-default viewer
+
+### Scenario: no time logged
+
+- WHEN there are zero entries in the requested range for the requested client
+- THEN the CLI exits with code 1 and a clear message
+- AND no files are written
+
+### Scenario: explicit date range
+
+- WHEN the user runs `halyard invoice acme --from 2026-04-01 --to 2026-04-15`
+- THEN the same logic as `--month` applies, scoped to that range
+
+## Requirement: halyard (bare command, REPL mode)
+
+The CLI MUST drop into an interactive Claude session when invoked with no
+subcommand.
+
+### Scenario: conversational logging
+
+- WHEN the user runs `halyard`
+- AND types "I just finished 2 hours on Globex"
+- THEN the agent proposes the timeclock entry, the user confirms,
+  the file is appended, and the agent waits for the next message
+
+### Scenario: query
+
+- WHEN the user types "how many hours have I billed ACME this quarter"
+- THEN the agent runs the equivalent `hledger -f time.timeclock` query
+- AND returns a table or short prose summary
+- AND no files are modified
+
+### Scenario: graceful exit
+
+- WHEN the user types `/quit` or sends EOF (Ctrl-D)
+- THEN the REPL exits cleanly with code 0

halyard-0.0.1/openspec/changes/v0-time-and-invoice/specs/data-model.md

@@ -0,0 +1,115 @@
+# Data Model Spec
+
+## Requirement: project layout
+
+A Halyard project is a directory containing exactly these files at the root
+after `halyard init`:
+
+- `halyard.toml` — project config (business name, default currency,
+  invoice counter, default invoice due-window in days)
+- `clients.toml` — array of clients
+- `projects.toml` — array of projects
+- `time.timeclock` — append-only hledger timeclock file
+- `invoices/` — directory of generated invoice `.md` and `.pdf` files
+- `.gitignore` — excludes `*.pdf` if the user opts in, plus
+  `.halyard-cache/` and `~/.halyard/`
+
+## Requirement: halyard.toml schema
+
+```toml
+[business]
+name = "M. Camaj Consulting"
+currency = "USD"
+default_due_days = 30
+
+[invoicing]
+counter = 0          # next invoice number suffix
+prefix = "{year}-{month:02d}-{client_slug}"
+```
+
+## Requirement: clients.toml schema
+
+```toml
+[[client]]
+slug = "acme"            # required, lowercase, [a-z0-9-]
+name = "Acme Corp"       # required
+hourly_rate = 150        # required, numeric
+email = "ap@acme.com"    # optional
+address = """            # optional, multi-line ok
+123 Main St
+Anytown, ST 12345
+"""
+```
+
+## Requirement: projects.toml schema
+
+```toml
+[[project]]
+slug = "auth-migration"   # required, scoped under client_slug
+client_slug = "acme"      # required, must match a client
+name = "Auth migration"   # required
+hourly_rate = 175         # optional override; falls back to client rate
+```
+
+## Requirement: timeclock format
+
+Time entries MUST conform to hledger timeclock format:
+
+```
+i YYYY-MM-DD HH:MM:SS <client-slug>:<project-slug>  optional comment
+o YYYY-MM-DD HH:MM:SS
+```
+
+The file is parseable by `hledger` directly, with no Halyard-specific
+extension. Compatibility with the broader plaintext-accounting ecosystem
+is a hard requirement — users SHOULD be able to drop Fava or hledger-web
+on top of `time.timeclock` and have it just work.
+
+## Requirement: invoice format
+
+Each invoice is a markdown file with YAML frontmatter:
+
+```markdown
+---
+invoice_number: 2026-04-acme-001
+client_slug: acme
+issue_date: 2026-04-30
+due_date: 2026-05-30
+currency: USD
+line_items:
+  - description: Auth migration
+    project_slug: auth-migration
+    hours: 12.5
+    rate: 175
+    amount: 2187.50
+total: 2187.50
+---
+
+# Invoice 2026-04-acme-001
+
+(rendered body — generated from the template)
+```
+
+The body is rendered from `templates/invoice.md.j2` if present in the
+project, otherwise from the built-in default template shipped with Halyard.
+
+## Requirement: invoice number sequencing
+
+Invoice numbers are sequential within a `(year, month, client)` tuple. The
+counter in `halyard.toml` is global; the prefix template controls how that
+counter renders into a final number.
+
+### Scenario: first invoice of the month for a client
+
+- WHEN the project has no prior invoice for ACME in 2026-04
+- THEN the next invoice for ACME in that month is `2026-04-acme-001`
+
+### Scenario: second invoice of the month for the same client
+
+- WHEN the project already has `2026-04-acme-001`
+- THEN the next is `2026-04-acme-002`
+
+### Scenario: different clients, same month
+
+- WHEN the project has `2026-04-acme-001` and the user invoices Globex
+- THEN the next is `2026-04-globex-001`

halyard-0.0.1/openspec/changes/v0-time-and-invoice/tasks.md

@@ -0,0 +1,64 @@
+# Tasks
+
+The implementation checklist for v0. Task IDs are referenced from the CLI
+stub via `NotImplementedError("v0 task X.Y")` markers — when you implement a
+task, update both the code and tick the box here.
+
+## 1. Project skeleton
+
+- [x] 1.1 Initialize Python package, pyproject.toml, ruff config
+- [x] 1.2 Set up Typer CLI entry point with stub commands
+- [ ] 1.3 Add CI: GitHub Actions running ruff + mypy + pytest on pushes/PRs
+- [ ] 1.4 Reserve `halyard` on PyPI (publish a 0.0.1 placeholder)
+- [ ] 1.5 Reserve a domain (halyard.dev or similar)
+
+## 2. Data model
+
+- [ ] 2.1 Pydantic models: `HalyardConfig`, `Client`, `Project`, `LineItem`,
+       `TimeclockEntry`, `Invoice`
+- [ ] 2.2 TOML readers/writers for `halyard.toml`, `clients.toml`,
+       `projects.toml` (round-trip safe; preserves comments where possible)
+- [ ] 2.3 Implement `halyard init` — creates the full project layout from
+       sensible defaults
+
+## 3. Time tracking
+
+- [ ] 3.1 Implement `halyard start <slug>` and `halyard stop`, including the
+       `~/.halyard/active` state file
+- [ ] 3.2 Implement `halyard log <text>`: send to Claude, render the
+       proposal, prompt for approval, append on confirm
+- [ ] 3.3 dateparser integration for "this morning", "yesterday", "last
+       Tuesday", etc., with a fixed reference timezone (the user's local)
+- [ ] 3.4 Timeclock parser/writer with round-trip safety (formatting,
+       comments)
+
+## 4. Invoicing
+
+- [ ] 4.1 Default Jinja invoice template — clean, professional, renders
+       well at letter and A4
+- [ ] 4.2 Implement `halyard invoice <client>` with `--month`, `--from`,
+       `--to` flags
+- [ ] 4.3 typst PDF rendering pipeline (subprocess; verify install on first
+       run with a friendly error if missing)
+- [ ] 4.4 Invoice number sequencing in `halyard.toml` per the spec scenarios
+- [ ] 4.5 Open the PDF after generation using the platform-default viewer
+
+## 5. Agent loop
+
+- [ ] 5.1 Anthropic SDK integration + tool definitions (read_text,
+       list_clients, list_projects, run_hledger, append_timeclock,
+       render_invoice, upsert_client, upsert_project)
+- [ ] 5.2 First version of `prompts/system.md`
+- [ ] 5.3 Approval prompt UX (Rich-based diff renderer, y/N/edit flow)
+- [ ] 5.4 Implement `halyard` (no args) REPL mode — readline history,
+       slash commands (`/quit`, `/help`, `/model`)
+
+## 6. Demo + launch
+
+- [ ] 6.1 Record the 60-second demo video (this is the actual deliverable
+       for v0 — the binary exists to make the video true)
+- [ ] 6.2 README polish: animated GIF, install instructions, the pitch
+- [ ] 6.3 Draft Show HN, Lobsters, /r/plaintextaccounting posts; sit on
+       them until the demo is good
+- [ ] 6.4 Tag and publish v0.1.0 on PyPI
+- [ ] 6.5 Cross-post the demo video to X with the project pitch line

halyard-0.0.1/openspec/project.md

@@ -0,0 +1,79 @@
+# Halyard — Project Context
+
+This file is loaded by OpenSpec on every change. It establishes shared
+conventions so each change proposal doesn't have to re-explain them.
+
+## Mission
+
+Halyard is a plain-text, agent-native financial OS for freelancers and
+one-person businesses. Time, expenses, clients, projects, and invoices live
+as plain-text files on the user's machine. An AI agent (Claude) reads and
+writes those files on the user's behalf.
+
+## Non-negotiables
+
+These constraints apply to every change. Any proposal that breaks them needs
+to explicitly justify the exception.
+
+1. **Local-first.** No required cloud service. Optional paid tiers may exist
+   later for sync or e-filing, but the core product runs offline against a
+   local folder.
+2. **Plain text forever.** All user data is stored in human-readable,
+   diff-friendly text formats with public specs:
+   - Time → [hledger timeclock](https://hledger.org/timeclock.html)
+   - Ledger → [Beancount](https://beancount.github.io/)
+   - Invoices → markdown with YAML frontmatter
+   - Config → TOML
+   No proprietary formats. No SQLite-as-source-of-truth.
+3. **Files are the source of truth.** Any UI (CLI, web, future GUI) is a
+   view onto the files. The agent edits the same files a human would.
+4. **No silent writes.** Any modification to user data is proposed to the
+   user with a diff and waits for approval. Read-only operations need no
+   approval.
+5. **MIT licensed.** Permissively. Forever.
+
+## Project layout (per Halyard project)
+
+A user's Halyard project directory contains:
+
+```
+my-business/
+├── halyard.toml          # business name, currency, invoice counter
+├── clients.toml          # array of clients
+├── projects.toml         # array of projects (linked to client_slug)
+├── time.timeclock        # hledger timeclock format
+├── ledger.beancount      # Beancount ledger (added in v1)
+├── invoices/             # generated invoice .md and .pdf files
+├── expenses/             # raw bank/receipt CSVs (added in v1)
+├── templates/            # optional user overrides
+│   └── invoice.md.j2
+└── .gitignore
+```
+
+Per-user agent state (skills, API keys, active timer) lives in
+`~/.halyard/`, not in the project folder.
+
+## Stack defaults
+
+- **Language:** Python 3.11+
+- **CLI:** Typer + Rich
+- **Models:** Pydantic v2
+- **Templating:** Jinja2
+- **PDF:** typst (subprocess)
+- **Time parsing:** dateparser
+- **Agent:** Anthropic SDK with tool use (single-turn loop in v0)
+- **Tests:** pytest with golden-file tests for renders
+- **Lint/format:** ruff
+
+Any deviation from this stack needs justification in the change's `design.md`.
+
+## How changes work
+
+Each change lives at `openspec/changes/<change-slug>/` with:
+
+- `proposal.md` — why & what's changing (high level)
+- `specs/*.md` — requirements with scenarios, in WHEN/THEN form
+- `design.md` — technical approach, choices, trade-offs
+- `tasks.md` — the implementation checklist
+
+Completed changes get archived to `openspec/changes/archive/YYYY-MM-DD-<slug>/`.

halyard-0.0.1/prompts/system.md

@@ -0,0 +1,76 @@
+# Halyard Agent — System Prompt (v0)
+
+You are Halyard, a plain-text, agent-native financial assistant for
+freelancers and one-person businesses. You help the user log time, manage
+clients and projects, and draft invoices. You operate against a known
+directory layout and well-defined file formats.
+
+## What you can rely on
+
+The user is in a Halyard project directory containing:
+
+- `halyard.toml` — project config (business name, default currency,
+  invoice counter)
+- `clients.toml` — clients with name, slug, hourly_rate, address, email
+- `projects.toml` — projects with slug, client_slug, name, optional rate
+  override
+- `time.timeclock` — append-only hledger timeclock file
+- `invoices/` — generated invoice markdown and PDF files
+
+If any of these are missing, ask the user to run `halyard init`. Do not
+attempt to create them yourself.
+
+## Time entries
+
+When the user describes work in natural language ("I just finished 2h on
+ACME's auth migration"), produce hledger timeclock entries:
+
+```
+i 2026-05-06 09:00:00 acme:auth-migration  Auth migration session
+o 2026-05-06 11:00:00
+```
+
+Default rules when information is missing:
+
+- If the user says "this morning," "yesterday afternoon," etc., resolve
+  against the current local date and time.
+- If the user gives only duration ("worked 2h on ACME"), use the most
+  recent stop time as the start. If there is no recent activity, use
+  current time minus the duration.
+- If the client or project slug is unknown, **do not invent it.** Propose
+  adding it via `upsert_client` / `upsert_project` first, asking for any
+  required fields you don't know (hourly_rate, full name).
+- The slug format is `client_slug:project_slug`, lowercase, hyphenated.
+
+## Invoices
+
+When asked to draft an invoice, read `time.timeclock`, sum hours by project
+for the requested client and date range, multiply by the appropriate rate
+(project-level override beats client-level rate), and produce line items.
+Use the template at `templates/invoice.md.j2` if the user has one,
+otherwise the built-in default. Increment the invoice counter in
+`halyard.toml`.
+
+If there are zero hours in the range, do not create an invoice. Tell the
+user.
+
+## Approval
+
+You never silently modify files. Every write to `time.timeclock`,
+`halyard.toml`, `clients.toml`, `projects.toml`, or anything in `invoices/`
+goes through a tool call that prompts the user for approval and shows a
+diff. Read-only operations (queries, summaries, hledger reports) need no
+approval.
+
+If the user declines a proposed change, do not retry the same change. Ask
+what they'd like to adjust.
+
+## Tone
+
+Concise. Direct. Terminal-native. Show, don't narrate — when you write a
+timeclock entry, just show the lines being added. When you generate an
+invoice, show the totals. Don't pad with phrases like "Sure, I'd be happy
+to help!" or "Let me think about that..."
+
+The user is a freelancer in a terminal who wants to get back to work. Save
+them keystrokes.

halyard-0.0.1/pyproject.toml

@@ -0,0 +1,71 @@
+[project]
+name = "halyard"
+version = "0.0.1"
+description = "Plain-text, agent-native financial OS for freelancers."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.11"
+authors = [{ name = "Kormilo LLC" }]
+keywords = ["freelance", "invoicing", "time-tracking", "accounting", "plaintext", "agent", "claude"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Office/Business :: Financial :: Accounting",
+]
+dependencies = [
+    "typer>=0.12",
+    "rich>=13.7",
+    "pydantic>=2.6",
+    "tomli>=2.0; python_version<'3.11'",
+    "tomli-w>=1.0",
+    "jinja2>=3.1",
+    "dateparser>=1.2",
+    "anthropic>=0.40",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "ruff>=0.5",
+    "mypy>=1.10",
+]
+
+[project.scripts]
+halyard = "halyard.cli:app"
+
+[project.urls]
+Homepage = "https://github.com/Kormiloio/Halyard"
+Repository = "https://github.com/Kormiloio/Halyard"
+Issues = "https://github.com/Kormiloio/Halyard/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/halyard"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "B", "UP", "C4", "SIM", "RUF"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["S101"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra -q"
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_return_any = true
+warn_unused_configs = true

halyard-0.0.1/src/halyard/__init__.py

@@ -0,0 +1,3 @@
+"""Halyard: plain-text, agent-native financial OS for freelancers."""
+
+__version__ = "0.0.1"

halyard-0.0.1/src/halyard/__main__.py

@@ -0,0 +1,4 @@
+from halyard.cli import app
+
+if __name__ == "__main__":
+    app()

halyard-0.0.1/src/halyard/cli.py

@@ -0,0 +1,82 @@
+"""Halyard CLI entry point.
+
+This module defines the command surface for v0. Each command currently raises
+NotImplementedError pointing at the task in
+`openspec/changes/v0-time-and-invoice/tasks.md` that will fill it in.
+"""
+from __future__ import annotations
+
+import typer
+from rich.console import Console
+
+app = typer.Typer(
+    name="halyard",
+    help=(
+        "Plain-text, agent-native financial OS. "
+        "Your books in plain text. Owned by you. Operated by Claude."
+    ),
+    no_args_is_help=False,
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+console = Console()
+
+
+@app.callback(invoke_without_command=True)
+def default(ctx: typer.Context) -> None:
+    """Drop into the interactive Claude REPL when invoked with no subcommand."""
+    if ctx.invoked_subcommand is None:
+        # TODO(v0 task 5.4): launch interactive agent REPL.
+        console.print(
+            "[bold cyan]Halyard[/] — interactive REPL not yet implemented "
+            "(see openspec/changes/v0-time-and-invoice/tasks.md task 5.4)."
+        )
+        raise typer.Exit(code=1)
+
+
+@app.command()
+def init() -> None:
+    """Scaffold a new Halyard project in the current directory."""
+    raise NotImplementedError("v0 task 2.3")
+
+
+@app.command()
+def log(
+    message: str = typer.Argument(..., help="Natural-language description of work."),
+) -> None:
+    """Log time from a free-form description (calls Claude to extract the entry)."""
+    raise NotImplementedError("v0 task 3.2")
+
+
+@app.command()
+def start(
+    slug: str = typer.Argument(..., help="client/project slug, e.g. acme/auth-migration"),
+) -> None:
+    """Start the active timer."""
+    raise NotImplementedError("v0 task 3.1")
+
+
+@app.command()
+def stop() -> None:
+    """Stop the active timer."""
+    raise NotImplementedError("v0 task 3.1")
+
+
+@app.command()
+def invoice(
+    client: str = typer.Argument(..., help="Client slug to invoice."),
+    month: str | None = typer.Option(
+        None, "--month", help="last | this | YYYY-MM"
+    ),
+    from_: str | None = typer.Option(
+        None, "--from", help="ISO date (inclusive lower bound)"
+    ),
+    to: str | None = typer.Option(
+        None, "--to", help="ISO date (inclusive upper bound)"
+    ),
+) -> None:
+    """Generate an invoice from logged time entries."""
+    raise NotImplementedError("v0 task 4.2")
+
+
+if __name__ == "__main__":
+    app()

halyard-0.0.1/templates/invoice.md.j2

@@ -0,0 +1,43 @@
+{# Default Halyard invoice template.
+   Rendered to markdown, then converted to PDF via typst.
+   Users can override this by creating templates/invoice.md.j2 in their
+   project directory. -#}
+---
+invoice_number: {{ invoice.invoice_number }}
+client_slug: {{ invoice.client_slug }}
+issue_date: {{ invoice.issue_date }}
+due_date: {{ invoice.due_date }}
+currency: {{ invoice.currency }}
+total: {{ "%.2f"|format(invoice.total) }}
+---
+
+# Invoice {{ invoice.invoice_number }}
+
+**{{ business.name }}**
+Issued: {{ invoice.issue_date }}
+Due: {{ invoice.due_date }}
+
+## Bill to
+
+**{{ client.name }}**
+{%- if client.address %}
+{{ client.address }}
+{%- endif %}
+{%- if client.email %}
+{{ client.email }}
+{%- endif %}
+
+## Line items
+
+| Description | Hours | Rate | Amount |
+|---|---:|---:|---:|
+{%- for item in invoice.line_items %}
+| {{ item.description }} | {{ "%.2f"|format(item.hours) }} | {{ invoice.currency }} {{ "%.2f"|format(item.rate) }} | {{ invoice.currency }} {{ "%.2f"|format(item.amount) }} |
+{%- endfor %}
+
+**Total: {{ invoice.currency }} {{ "%.2f"|format(invoice.total) }}**
+
+---
+
+Payable within {{ (invoice.due_date - invoice.issue_date).days }} days.
+Thank you for your business.

halyard-0.0.1/tests/test_cli_smoke.py

@@ -0,0 +1,24 @@
+"""Smoke tests for the CLI surface.
+
+These do not exercise behavior — that's what the v0 task tests will do. They
+just guarantee that the CLI app constructs and exposes the expected commands.
+"""
+from __future__ import annotations
+
+from typer.testing import CliRunner
+
+from halyard.cli import app
+
+runner = CliRunner()
+
+
+def test_help_runs() -> None:
+    result = runner.invoke(app, ["--help"])
+    assert result.exit_code == 0
+    assert "Halyard" in result.stdout or "halyard" in result.stdout
+
+
+def test_v0_commands_registered() -> None:
+    result = runner.invoke(app, ["--help"])
+    for cmd in ("init", "log", "start", "stop", "invoice"):
+        assert cmd in result.stdout, f"command {cmd!r} not registered"