Repository Guidelines

Project Structure & Module Organization

```
cmd/
```
: Cobra-based CLI commands (
```
build
```
,
```
serve
```
,
```
init
```
,
```
freeze
```
,
```
test
```
, etc.).
```
document/
```
: Core build pipeline (config, parsing, templates, images, URIs).
```
cliutils/
```
: Small CLI helpers (printing, prompts).
```
testdata/
```
and
```
document/testdata/
```
: Input/fixture files for tests.
```
main.go
```
: Entrypoint wiring version info to the CLI.
```
.github/workflows/
```
: CI running
```
go test
```
and a release build.

Build, Test, and Development Commands

```
go test ./...
```
: Run all unit tests. Add
```
-race
```
locally for data race checks.
```
go run . --help
```
: Preview CLI usage; try commands like
```
go run . build -s
```
.
```
go build -o w .
```
: Compile the CLI locally.

Versioned build (matches CI):

go build -ldflags="-X 'main.version=$(git describe --tags --always)'" -o w .

Hygiene:
```
go fmt ./...
```
and
```
go vet ./...
```
before sending PRs.

Coding Style & Naming Conventions

Go formatting is canonical: run
```
go fmt
```
and keep imports tidy.
Prefer idiomatic, small packages and clear exported names (CamelCase); files use
```
snake_case.go
```
.
Errors: wrap with context (
```
fmt.Errorf("doing X: %w", err)
```
) and log via
```
slog
```
where appropriate.
Keep CLI flags consistent with existing ones (
```
-v/--verbose
```
,
```
-q/--quiet
```
).

Testing Guidelines

Use the standard
```
testing
```
package; name files
```
*_test.go
```
and tests
```
TestXxx
```
.
Favor table-driven tests; place fixtures under
```
testdata/
```
.
Ensure deterministic outputs (templates, image ops) and cover edge cases.
Run
```
go test ./...
```
(and
```
-race
```
locally) before committing.

Commit & Pull Request Guidelines

Commits: imperative, concise subject (≤72 chars). Examples:
```
fix reloader nil channel
```
,
```
feat: add build summary
```
.
Reference issues/PRs when applicable (
```
(#123)
```
). Squash trivial fixups.
PRs: include a clear description, reproduction or motivation, test coverage for changes, and notes on docs updates (README/CLI help) if behavior changes.

Architecture Overview

CLI is composed in
```
cmd/root.go
```
; core build logic lives in
```
document/
```
(via
```
Substructure.ExecuteAll
```
).
```
build -s
```
serves
```
dist/
```
on
```
localhost:8100
```
with live reload.

Project Structure & Module Organization

cmd/

: Cobra-based CLI commands (

build

serve

init

freeze

test

, etc.).

document/

: Core build pipeline (config, parsing, templates, images, URIs).

cliutils/

: Small CLI helpers (printing, prompts).

testdata/

and

document/testdata/

: Input/fixture files for tests.

main.go

: Entrypoint wiring version info to the CLI.

.github/workflows/

: CI running

go test

and a release build.

Build, Test, and Development Commands

go test ./...

: Run all unit tests. Add

-race

locally for data race checks.

go run . --help

: Preview CLI usage; try commands like

go run . build -s

go build -o w .

: Compile the CLI locally.

Versioned build (matches CI):

go build -ldflags="-X 'main.version=$(git describe --tags --always)'" -o w .

Hygiene:

go fmt ./...

and

go vet ./...

before sending PRs.

Coding Style & Naming Conventions

Go formatting is canonical: run

go fmt

and keep imports tidy.

Prefer idiomatic, small packages and clear exported names (CamelCase); files use

snake_case.go

Errors: wrap with context (

fmt.Errorf("doing X: %w", err)

) and log via

slog

where appropriate.

Keep CLI flags consistent with existing ones (

-v/--verbose

-q/--quiet

Commit & Pull Request Guidelines

Commits: imperative, concise subject (≤72 chars). Examples:

fix reloader nil channel

feat: add build summary

Reference issues/PRs when applicable (

(#123)

). Squash trivial fixups.

PRs: include a clear description, reproduction or motivation, test coverage for changes, and notes on docs updates (README/CLI help) if behavior changes.

Repository Guidelines

Repository Guidelines

Project Structure & Module Organization

Build, Test, and Development Commands

Coding Style & Naming Conventions

Testing Guidelines

Commit & Pull Request Guidelines

Architecture Overview

Related Skills

Markdown Converter

Nano Banana Pro

1password

Repository Guidelines

Project Structure & Module Organization

Build, Test, and Development Commands

Coding Style & Naming Conventions

Testing Guidelines

Commit & Pull Request Guidelines

Architecture Overview