agentleFS
jjanuszczakjjanuszczak/margo/AGENTS.md

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.

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
  1. Distinctive:

    default theme plus deck-local custom themes

    line 22
  2. Distinctive:

    Use the product docs for intent and scope boundaries.

    line 45
  3. Distinctive:

    add, duplicate, reorder, and trash slides through shared CLI operations

    line 96
  4. Distinctive:

    When choosing work, check:

    line 132
  5. Distinctive:

    Prefer Go code to provide:

    line 157
  6. Distinctive:

    Avoid pushing presentation-specific HTML/CSS shape decisions into Go unless there is a strong cross-cutting reason.

    line 165
  7. Distinctive:

    If a helper can validate or resolve something for many shortcodes or templates, it is a good candidate for Go.

    line 181
  8. Distinctive:

    If a helper only exists to assemble one component's final markup shape, it probably belongs in template composition instead.

    line 183
  9. Distinctive:

    Do not quietly collapse those layers together.

    line 192
  10. Distinctive:

    Treat engine/theme decoupling as a first-class rule, not a stylistic preference.

    line 194
  11. Distinctive:

    Avoid making themes depend on ad hoc engine-only template fields when the same behavior can be derived from rendered markup or stable …

    line 196
  12. Distinctive:

    Prefer theme behavior that keys off HTML structure, CSS classes, declared assets, or reusable template primitives rather than …

    line 197
  13. Distinctive:

    If the engine must expose something to templates, prefer a stable mechanism-level helper over a narrow feature flag that couples one theme …

    line 198
  14. Distinctive:

    When deck-level and theme-level customization both exist, prefer explicit local override behavior over magic lookup or deep inheritance.

    line 224
  15. Very specific:

    After installation, reload the skills in your interactive session using /skills reload.

    line 259
  16. Distinctive:

    Prefer committed fixtures and temp directories in tests over ad hoc throwaway decks.

    line 348
  17. Distinctive:

    Create and use a test deck:

    line 364
  18. Distinctive:

    Use a non-default preview port when needed:

    line 373
  19. Very specific:

    Use a disposable copy of a committed deck for editing and structural-operation QA.

    line 435
  20. Very specific:

    Verify source save/undo, external edits, note creation/reopening/preview, thumbnails, app/editor themes, window/divider resizing, and …

    line 436
  21. Distinctive:

    When a change affects user-facing output, prefer checking:

    line 455
  22. Very specific:

    Do not expect margo build to work from repo root.

    line 490
  23. Distinctive:

    Do not conflate them.

    line 498
  24. Distinctive:

    If a PDF looks wrong, compare:

    line 500
  25. Distinctive:

    do not move shortcode-specific presentational logic into Go unless it is genuinely reusable

    line 526
  26. Distinctive:

    prefer template composition over new feature-specific helper code

    line 527
  27. Distinctive:

    when adding helper functions, ask whether they are mechanism-level or component-specific

    line 528
  28. Distinctive:

    When changing deck-level wrappers or CSS assumptions, verify both pipelines.

    line 534
  29. Distinctive:

    When implementing a change:

    line 562
  30. Distinctive:

    Update all affected layers together:

    line 570
  31. Distinctive:

    Verify with the smallest correct test scope first.

    line 577
  32. Distinctive:

    If output changes, verify with a real deck flow.

    line 579
  33. Distinctive:

    If the change touches theme rendering, check both:

    line 581
  34. Distinctive:

    If you add template helpers in Go, explicitly check whether they are:

    line 585
  35. Distinctive:

    Use relative Markdown links in repo docs.

    line 591
  36. Distinctive:

    If you are unsure what to do next:

    line 603
  37. Distinctive:

    use the committed decks

    line 604
  38. Distinctive:

    prefer tightening the current model over inventing a new subsystem

    line 605
  39. Distinctive:

    check whether the problem is really product behavior, theme behavior, or export behavior

    line 606
  40. Distinctive:

    do not “fix PDF” by damaging the HTML-first experience

    line 607

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

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 init
  • margo build
  • margo serve
  • margo clean
  • margo 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.yaml parsing 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:

  1. the PRD
  2. the implementation plan
  3. open GitHub issues
  4. 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 --port for 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-chart markup is a good theme-side decision
  • requiring a theme to read a special field like .HasCharts is 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 workspace

After 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.yaml parsing 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/margo

Run directly:

go run ./cmd/margo help

Create and use a test deck:

./bin/margo new my-deck
cd my-deck
../bin/margo build
../bin/margo serve

Use a non-default preview port when needed:

../bin/margo serve --port 1414

Install a vendored theme from Git:

../bin/margo theme add https://example.com/brand-theme.git --ref v0.1.0
../bin/margo theme list

Important limitation:

  • theme add currently 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 dev

Development 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 -- --check

Use 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 Thumbnail

Native 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/html

Manual checks

When a change affects user-facing output, prefer checking:

  • examples/reference-deck
  • examples/benchmark-deck
  • examples/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.sh

This 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:

  1. Identify whether it is:
    • product behavior
    • theme behavior
    • scaffold behavior
    • test-only behavior
  2. Update all affected layers together:
    • implementation
    • scaffold output if applicable
    • committed fixtures if applicable
    • tests
    • docs for user-facing behavior
  3. Verify with the smallest correct test scope first.
  4. If output changes, verify with a real deck flow.
  5. If the change touches theme rendering, check both:
    • the default/reference deck
    • the ArCa dogfood deck
  6. 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

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.