margo
AGENTS.md2 starsChanged 17 days agoApache-2.0View on GitHub
This file is for a new developer or agent picking up margo. It is intentionally practical. Read this first so you understand: - what the repo is - what works today - where the important code lives - how to verify changes safely - which areas are still in flux margo is a Go presentation engine and CLI with an optional Rust + Tauri 2 desktop app for authoring Markdown slide decks using a Hugo-like project model. Current shape: -…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository3 other files it gives its agents.
- github-issue-managerSkill
- git-workflow-lifecycleSkill
- release-managerSkill
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
40 rules. About 0 are common, 36 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈36
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 22
default theme plus deck-local custom themes
- Distinctive: line 45
Use the product docs for intent and scope boundaries.
- Distinctive: line 96
add, duplicate, reorder, and trash slides through shared CLI operations
- Distinctive: line 132
When choosing work, check:
- Distinctive: line 157
Prefer Go code to provide:
- Distinctive: line 165
Avoid pushing presentation-specific HTML/CSS shape decisions into Go unless there is a strong cross-cutting reason.
- Distinctive: line 181
If a helper can validate or resolve something for many shortcodes or templates, it is a good candidate for Go.
- Distinctive: line 183
If a helper only exists to assemble one component's final markup shape, it probably belongs in template composition instead.
- Distinctive: line 192
Do not quietly collapse those layers together.
- Distinctive: line 194
Treat engine/theme decoupling as a first-class rule, not a stylistic preference.
- Distinctive: line 196
Avoid making themes depend on ad hoc engine-only template fields when the same behavior can be derived from rendered markup or stable …
- Distinctive: line 197
Prefer theme behavior that keys off HTML structure, CSS classes, declared assets, or reusable template primitives rather than …
- Distinctive: line 198
If the engine must expose something to templates, prefer a stable mechanism-level helper over a narrow feature flag that couples one theme …
- Distinctive: line 224
When deck-level and theme-level customization both exist, prefer explicit local override behavior over magic lookup or deep inheritance.
- Very specific: line 259
After installation, reload the skills in your interactive session using /skills reload.
- Distinctive: line 348
Prefer committed fixtures and temp directories in tests over ad hoc throwaway decks.
- Distinctive: line 364
Create and use a test deck:
- Distinctive: line 373
Use a non-default preview port when needed:
- Very specific: line 435
Use a disposable copy of a committed deck for editing and structural-operation QA.
- Very specific: line 436
Verify source save/undo, external edits, note creation/reopening/preview, thumbnails, app/editor themes, window/divider resizing, and …
- Distinctive: line 455
When a change affects user-facing output, prefer checking:
- Very specific: line 490
Do not expect margo build to work from repo root.
- Distinctive: line 498
Do not conflate them.
- Distinctive: line 500
If a PDF looks wrong, compare:
- Distinctive: line 526
do not move shortcode-specific presentational logic into Go unless it is genuinely reusable
- Distinctive: line 527
prefer template composition over new feature-specific helper code
- Distinctive: line 528
when adding helper functions, ask whether they are mechanism-level or component-specific
- Distinctive: line 534
When changing deck-level wrappers or CSS assumptions, verify both pipelines.
- Distinctive: line 562
When implementing a change:
- Distinctive: line 570
Update all affected layers together:
- Distinctive: line 577
Verify with the smallest correct test scope first.
- Distinctive: line 579
If output changes, verify with a real deck flow.
- Distinctive: line 581
If the change touches theme rendering, check both:
- Distinctive: line 585
If you add template helpers in Go, explicitly check whether they are:
- Distinctive: line 591
Use relative Markdown links in repo docs.
- Distinctive: line 603
If you are unsure what to do next:
- Distinctive: line 604
use the committed decks
- Distinctive: line 605
prefer tightening the current model over inventing a new subsystem
- Distinctive: line 606
check whether the problem is really product behavior, theme behavior, or export behavior
- Distinctive: line 607
do not “fix PDF” by damaging the HTML-first experience
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
AGENTS.md
This file is for a new developer or agent picking up margo.
It is intentionally practical. Read this first so you understand:
- what the repo is
- what works today
- where the important code lives
- how to verify changes safely
- which areas are still in flux
What This Repo Is
margo is a Go presentation engine and CLI with an optional Rust + Tauri 2
desktop app for authoring Markdown slide decks using a Hugo-like project model.
Current shape:
- local CLI for automation, scaffolding, builds, packaging, and publishing
- desktop companion for visual review and source editing, targeting macOS and Omarchy/Arch Linux
- HTML-first output
- scaffold/build/serve workflow
- default theme plus deck-local custom themes
- HTML, PDF, and editable PPTX output with format-specific limits
- Git-based vendored theme install workflow
This is not a finished product. It is beyond prototype scaffolding, but still actively evolving in product scope, theme contract, and export quality.
Read These First
Start with:
- README.md
- docs/product/PRD.md
- docs/product/implementation-plan.md
- docs/AUTHORING_GUIDE.md
For desktop work, also read:
- Desktop development and use
- Desktop PRD
- Desktop implementation plan
- Desktop runtime and protocol
Historical context:
- docs/archive/sprints
Use the product docs for intent and scope boundaries. Use the authoring guide for what the tool is supposed to feel like for end users.
Current Product State
Working CLI surface
margo new <deck-name>margo initmargo buildmargo servemargo cleanmargo new slide <name>margo new note <name> --slide <bundle>margo slide insert <name> ...margo slide move <slide> ...margo slide delete <slide>margo new theme <name>margo theme add <repo> [--ref <rev>] [--name <local-name>]margo theme update <name>margo theme list
Implemented platform pieces
margo.yamlparsing and project discovery- YAML slide front matter
- Markdown rendering with Goldmark
- deck-local themes under
themes/<name>/ - per-slide layouts
- slide archetypes
- draft and hidden filtering
- notes preservation without normal slide rendering
- sections and synthetic section divider slides
- deck-local shortcodes
- project-local Markdown includes
- deck-level snippet injection at approved locations
- deck and slide asset staging
- interactive HTML output
- print-oriented HTML output
- PDF generation from print HTML
- vendored theme install/list
- benchmark and regression fixtures
- release archive script
Desktop app MVP
- Rust + Tauri 2 shell with a bundled Go engine using a private JSON-lines protocol
- new-project wizard using the canonical Go scaffold, optional Git theme import, project picker, and recent projects; no separate installed CLI required
- rendered slide thumbnails, overview, and a preview that fits the pane on resize
- Monaco Markdown editor with auto-save, manual save, per-file undo/redo, and conflict handling
- named bundle note creation/editing and rendered notes preview
- add, duplicate, reorder, and trash slides through shared CLI operations
- local image/video insertion and HTML/PDF/PPTX export entry points
- graphical tiling UI that writes canonical nested shortcodes when the active theme declares the required support; it does not modify themes automatically
- agent-skill prompt handoff with project, theme, source-path, and skill context; the app does not run an AI agent
- native Projects menu, icon toolbar, and welcome actions for new/open projects
- light, dark, system, and Omarchy palette appearance with independent editor themes
Apple Silicon macOS builds and native workflows have been checked locally. A debug build has also launched in an Omarchy session. Full Omarchy/Hyprland acceptance of palette matching, dialogs, Wayland geometry/focus, and exports remains pending. CI build jobs are configured for macOS, Ubuntu/WebKitGTK, and Arch; configuration alone is not passing evidence.
Implemented but still rough
- PDF fidelity and environment reliability
- theme print overrides beyond the default/productized examples
- theme portability UX beyond the current repo-root install assumption
- manifest-driven sequencing beyond the current loader path
Not done
- full PPTX shortcode/theme parity
- deck/theme settings panels, selected-slide presentation start, export cancellation, and zoom presets
- signed/notarized desktop distribution and automatic updates
- presenter mode
- plugin architecture
- multi-deck repo workflow
- arbitrary slide sizes and ratios beyond the current defaults
Current Priorities
There is no single active sprint doc you should treat as the source of truth.
When choosing work, check:
- the PRD
- the implementation plan
- open GitHub issues
- whether the change tightens the current model or expands product scope
As of now, the highest-risk product areas are:
- PDF quality and validation
- theme API stability
- authoring polish and CLI ergonomics
- desktop source safety, native preview geometry/focus, and Omarchy acceptance
Recent additions that matter:
- optional Tauri desktop app with project creation, Monaco, rendered thumbnails, notes preview, tiling controls, agent-skill prompt handoff, and Omarchy palette support
- theme-aware print templates
- vendored theme installation via
theme add serve --portfor non-default preview ports
Architectural Principles
These are important project-level design choices, not incidental implementation details.
1. Keep the Go engine generic
Prefer Go code to provide:
- parsing
- validation
- asset resolution
- staging
- model shaping
- generic template helper primitives
Avoid pushing presentation-specific HTML/CSS shape decisions into Go unless there is a strong cross-cutting reason.
2. Keep rendering shape in templates
Shortcodes, layouts, and future partials should own:
- markup structure
- class composition
- inline style composition where needed
- theme-facing presentational decisions
Example:
- generic helpers like required param checks and asset resolution belong in Go
- figure-specific class/style assembly belongs in shortcode templates, not in Go helpers
3. Prefer reusable primitives over named feature logic
If a helper can validate or resolve something for many shortcodes or templates, it is a good candidate for Go.
If a helper only exists to assemble one component's final markup shape, it probably belongs in template composition instead.
4. Keep deck, theme, and shortcode concerns separate
Margo should preserve a clear boundary:
- engine mechanics in Go
- theme and deck presentation in templates
- author-facing content usage in Markdown/front matter
Do not quietly collapse those layers together.
Treat engine/theme decoupling as a first-class rule, not a stylistic preference.
- Avoid making themes depend on ad hoc engine-only template fields when the same behavior can be derived from rendered markup or stable generic helpers.
- Prefer theme behavior that keys off HTML structure, CSS classes, declared assets, or reusable template primitives rather than feature-specific booleans injected from Go.
- If the engine must expose something to templates, prefer a stable mechanism-level helper over a narrow feature flag that couples one theme behavior to one internal implementation detail.
Example:
- loading a chart runtime because the deck contains
.shortcode-chartmarkup is a good theme-side decision - requiring a theme to read a special field like
.HasChartsis tighter coupling and should be avoided unless there is a strong cross-cutting reason
5. Keep the desktop app on the canonical engine
Go owns project interpretation, file revisions, safe mutations, and rendering. Rust owns native lifecycle, dialogs, sidecar management, and preview placement. The JS UI owns buffers and interaction state. Do not duplicate Margo parsing or rendering in Rust/JS, or replace source files with an editor-owned document model.
The preview runs in a separate unprivileged native webview, with generated files served from a read-only random-token loopback URL. Never give theme-authored HTML the editor's native capabilities. Bundle the engine from the same checkout.
The content model stores named-note paths relative to the bundle. Desktop source
reads/saves require project-relative paths. Preserve that conversion in snapshots.
App/editor appearance is independent of the deck's theme. On Omarchy, the app may
read the active system palette for its own controls; this must not change deck
rendering. Use the approved assets/new-logo-*.png wordmarks rather than creating
replacement branding.
6. Favor explicit override models
When deck-level and theme-level customization both exist, prefer explicit local override behavior over magic lookup or deep inheritance.
This already applies to shortcodes and should remain the bias for future features such as partials.
Repo Layout
Top-level directories:
cmd/
desktop/
docs/
examples/
internal/
scripts/
skills/Agent Skills
Predefined agent skills are stored in the skills/ directory. These skills provide specialized workflows and domain expertise for Gemini CLI when working on the margo project.
The desktop skill handoff reads the selected deck's .agents/skills/ files and
their declared Markdown references. It prepares a project-aware prompt for copying
to an external agent; it does not launch an agent or grant that agent filesystem
access.
- github-issue-manager: Manages the creation of GitHub issues and development branches. Use this to start work on a new feature or bug fix.
- git-workflow-lifecycle: Automates the end-to-end lifecycle of a feature branch, from submission (commit, push, PR) to cleanup.
To ensure these skills are active in your environment, they should be installed into the workspace scope:
gemini skills install skills/github-issue-manager.skill --scope workspace
gemini skills install skills/git-workflow-lifecycle.skill --scope workspaceAfter installation, reload the skills in your interactive session using /skills reload.
Important code areas
- desktop/src Tauri web UI, Monaco adapter, app appearance, and buffer reconciliation
- desktop/src-tauri/src/main.rs Native shell, dialogs, bundled engine lifecycle, preview isolation and geometry
- desktop/scripts Target-specific Go sidecar builds, approved-logo icons, and engine measurements
- internal/desktop Private app protocol, project snapshots, source saves, preview server, notes and thumbnails
- internal/cli/desktop.go Private engine entry point and reuse of canonical CLI slide operations
- cmd/margo/main.go CLI entrypoint
- internal/cli Command dispatch and user-facing CLI flows
- internal/config
margo.yamlparsing and validation - internal/project Deck-root discovery
- internal/content Slide discovery, front matter parsing, notes extraction, includes
- internal/deck In-memory deck model, filtering, section building
- internal/theme Theme loading, metadata, validation, install workflow
- internal/shortcode Shortcode rendering and resolution
- internal/output/render Shared render helpers used by multiple output pipelines
- internal/output/html Interactive HTML rendering pipeline
- internal/output/printhtml Static print-oriented HTML rendering pipeline
- internal/output/pdf PDF generation from print HTML
- internal/scaffold Deck/theme/slide scaffolding and default theme templates
- internal/serve Preview server and PDF export endpoint
- internal/watch File watching for rebuild flows
- internal/manifest Manifest loading support
- internal/ignore Ignore rules for project walking/build inputs
Example Decks And Fixtures
These matter a lot:
- examples/reference-deck Main regression/acceptance fixture
- examples/benchmark-deck Committed 20-slide benchmark deck
- examples/arca-investor-memo Real dogfood deck and the main theme-aware PDF fidelity check
Use them for:
- manual QA
- regression tests
- validating author-facing behavior
- checking whether theme changes hold up on a real deck
Prefer committed fixtures and temp directories in tests over ad hoc throwaway decks.
How To Build And Run
Build the CLI:
go build -o ./bin/margo ./cmd/margoRun directly:
go run ./cmd/margo helpCreate and use a test deck:
./bin/margo new my-deck
cd my-deck
../bin/margo build
../bin/margo serveUse a non-default preview port when needed:
../bin/margo serve --port 1414Install a vendored theme from Git:
../bin/margo theme add https://example.com/brand-theme.git --ref v0.1.0
../bin/margo theme listImportant limitation:
theme addcurrently assumes the Git repo root is itself a single Margo theme- it does not yet install a theme from a subdirectory inside a larger monorepo
Desktop development
From the repository root, install Go 1.22+, Node.js 22+, stable Rust, and the Tauri platform prerequisites, then run:
cd desktop
npm ci
npm run devDevelopment and packaging build the Go sidecar automatically. For a local macOS
app, run npm run build -- --debug --bundles app from desktop/; launch
desktop/src-tauri/target/debug/bundle/macos/Margo.app from Finder. Quit and reopen
a running instance after rebuilding. Native Arch build and portal instructions
are in the desktop guide.
Testing And Verification
Full suite
env GOCACHE=/Users/johnjanuszczak/Projects/margo/.gocache go test ./...In restricted environments, set GOCACHE explicitly as above.
Focused test areas
- content parsing:
./internal/content - themes/install/options:
./internal/theme - interactive rendering:
./internal/output/html - print rendering:
./internal/output/printhtml - PDF glue:
./internal/output/pdf - CLI workflows:
./internal/cli - desktop protocol, source safety, notes and previews:
./internal/desktop
Desktop checks
npm test --prefix desktop
npm run web:build --prefix desktop
cargo fmt --manifest-path desktop/src-tauri/Cargo.toml -- --checkUse a disposable copy of a committed deck for editing and structural-operation QA. Verify source save/undo, external edits, note creation/reopening/preview, thumbnails, app/editor themes, window/divider resizing, and exports. Chrome/Chromium supplies thumbnail capture and PDF export. The optional real-capture test is:
MARGO_DESKTOP_THUMBNAIL_TEST=1 go test ./internal/desktop -run ThumbnailNative acceptance must run on the actual OS. Linux compilation does not verify Omarchy's Wayland geometry, input, GPU rendering, or desktop file-picker portals.
Benchmark
go test -run '^$' -bench BenchmarkBenchmarkDeckBuildFlow ./internal/output/htmlManual checks
When a change affects user-facing output, prefer checking:
examples/reference-deckexamples/benchmark-deckexamples/arca-investor-memo- a fresh scaffolded deck from
margo new
Release / Packaging
Release archive script:
- scripts/release.sh
Example:
VERSION=0.1.0 ./scripts/release.shThis builds versioned archives that bundle:
- the binary
- README.md
- docs/AUTHORING_GUIDE.md
Version stamping comes from:
- internal/version/version.go
The script packages the CLI only. The Homebrew tap also installs the CLI, not the
app. Desktop builds use Tauri separately; signed/notarized app releases, automatic
updates, and .pkg packaging are not configured. See release procedures.
Common Sharp Edges
1. The repo root is not a deck
margo source itself is not a presentation project.
Do not expect margo build to work from repo root.
2. PDF has two separate concerns
There are two classes of PDF problems:
- print HTML correctness
- browser/headless environment behavior
Do not conflate them.
If a PDF looks wrong, compare:
- interactive HTML
- print HTML
- generated PDF
The print pipeline now uses a dedicated static print artifact rather than rewriting the interactive deck HTML.
3. Theme behavior is convention-heavy
The default theme is still the primary reference contract.
Changes to:
- layout names
- theme metadata
- option names
- slide wrapper structure
- print template behavior
will ripple into:
- scaffolding
- fixtures
- docs
- tests
- real deck fidelity
Also be careful about architectural drift:
- do not move shortcode-specific presentational logic into Go unless it is genuinely reusable
- prefer template composition over new feature-specific helper code
- when adding helper functions, ask whether they are mechanism-level or component-specific
4. The print and interactive pipelines are related but not identical
internal/output/html and internal/output/printhtml share render logic, but they are not the same shell.
When changing deck-level wrappers or CSS assumptions, verify both pipelines.
5. Keep features disciplined
The product direction avoids turning authoring into a second programming language.
Prefer:
- explicit, constrained features
- deck-local and theme-local customization
- minimal extension points with clear ownership
- generic engine primitives with presentational composition in templates
Avoid:
- broad DSLs
- implicit magic behavior
- arbitrary generalization unless the product needs it
- growing a library of shortcode-specific Go helpers when template logic is sufficient
6. Desktop notes and preview boundaries
Named notes live at slides/<bundle>/notes/<name>.md. The desktop notes reader
works independently of a theme's Notes controls; published controls still require
presentation.navigation.notes: true and theme support. Slide previews fit the
rendered stage at a fixed source viewport. Do not fix resizing by changing theme
breakpoints or enabling page scrollbars that overlap native controls.
How To Work Safely
When implementing a change:
- Identify whether it is:
- product behavior
- theme behavior
- scaffold behavior
- test-only behavior
- Update all affected layers together:
- implementation
- scaffold output if applicable
- committed fixtures if applicable
- tests
- docs for user-facing behavior
- Verify with the smallest correct test scope first.
- If output changes, verify with a real deck flow.
- If the change touches theme rendering, check both:
- the default/reference deck
- the ArCa dogfood deck
- If you add template helpers in Go, explicitly check whether they are:
- generic mechanism helpers that could serve multiple shortcodes/layouts
- presentational helpers that should stay in templates instead
Documentation Conventions
Use relative Markdown links in repo docs.
Good:
[PRD](./docs/product/PRD.md)[Authoring Guide](./docs/AUTHORING_GUIDE.md)- from
docs/:[reference deck](../examples/reference-deck)
Avoid:
- absolute local filesystem paths in repo Markdown
Practical Advice
If you are unsure what to do next:
- use the committed decks
- prefer tightening the current model over inventing a new subsystem
- check whether the problem is really product behavior, theme behavior, or export behavior
- do not “fix PDF” by damaging the HTML-first experience
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

