This template provides the required .labyricorn/ publishing records, assistant guidance files (AGENTS.md), devlog structure, and the standalone devlog_editor.py management utility for local validation and GUI editing.

Overview

Projects published on Labyricorn maintain their own exhibition pages and development logs directly inside their Git repositories under the .labyricorn/ directory. The Labyricorn site importer periodically synchronizes these records as read-only content.

This template includes:

.labyricorn/ publishing structure: Validated Lektor-format records for project identity and development logs.
devlog_editor.py: Standalone GUI and CLI tool for managing devlog entries, validating publishing contracts, and safely publishing changes.
AGENTS.md instructions: Scoped assistant instructions at repository root and publishing directories to ensure AI assistants adhere to the publishing contract.
.gitignore: Configured exclusions for Python environments, caches, and build artifacts.

Directory Structure

.
├── .gitignore
├── .labyricorn/
│   ├── AGENTS.md               # Assistant instructions for publishing content
│   ├── README.md               # Publishing structure documentation
│   ├── project/
│   │   ├── AGENTS.md           # Instructions for the project exhibition record
│   │   ├── contents.lr         # Project identity and exhibition narrative
│   │   └── <optional logo>     # Project logo (PNG, JPEG, WebP)
│   └── devlog/
│       ├── AGENTS.md           # Instructions for devlog records
│       ├── contents.lr         # Devlog index record
│       └── <entry-slug>/       # (Optional) Devlog entry directories
│           ├── contents.lr     # Devlog entry record
│           └── <optional img>  # Entry attachments (PNG, JPEG, WebP)
├── AGENTS.md                   # Assistant instructions for the repository
├── devlog_editor.py            # Standalone devlog editor & validator
├── LICENSE                     # License file
└── README.md                   # Project documentation

Getting Started

1. Configure the Project Identity

Edit .labyricorn/project/contents.lr to set your project details:

_model: project
---
schema_version: 1
---
project_id: my-project-id
---
title: My Project Title
---
summary:

A concise summary of the project for listings and cards.
---
status: active
---
started: 2026-08-23
---
author: Author Name
---
repository_url: https://git.labyricorn.com/Owner/my-project
---
default_branch: main
---
tags: python, web, tool
---
body:

An exhibition narrative describing the project background, goals, and features.

Project Fields:

project_id: Stable lowercase hyphenated slug (e.g. my-project).
title: Display title for the project.
summary: Short multi-line summary.
status: One of active, released, maintained, or archived.
started: Start date in YYYY-MM-DD format.
author: Author or organization name.
repository_url: Public credential-free HTTPS Git URL.
default_branch: Target branch name (e.g. main).
logo: (Optional) Local filename of an image inside .labyricorn/project/.
tags: Comma-separated technology or topic labels.
body: Markdown narrative of the project.

2. Configure the Devlog Index

Edit .labyricorn/devlog/contents.lr to customize the devlog title and summary:

_model: devlog
---
schema_version: 1
---
title: My Project development log
---
summary: Milestones and development updates for My Project.

3. Add Devlog Entries

To add an entry manually, create a directory under .labyricorn/devlog/<entry-slug>/ containing contents.lr:

_model: devlog-entry
---
schema_version: 1
---
title: Initial Project Milestone
---
date: 2026-08-23
---
author: Author Name
---
summary:

Overview of the milestone accomplishments.
---
tags: release, setup
---
source_commit: <40-character-commit-hash>
---
body:

Detailed Markdown description of the milestone, technical decisions, and progress.

Alternatively, use devlog_editor.py to create and edit entries interactively.

Devlog Editor

The included devlog_editor.py script is a standalone utility with zero external dependencies (uses Python standard library and Tkinter).

CLI Validation

Validate all project and devlog records without opening a GUI:

python devlog_editor.py --validate

Graphical Editor

Launch the Tkinter management interface to view repository status, draft entries, and publish updates:

python devlog_editor.py

Features of the GUI editor:

Repository status: Displays current branch, remote, and ahead/behind counts.
Entry manager: Create, edit, and delete devlog entries with automatic slug and date handling.
Publishing safety: Stages and commits only .labyricorn/ publishing files, leaving application source files untouched.

Publishing Rules & Constraints

The Labyricorn site importer enforces strict validation rules on imported repositories:

Native Lektor Records: Records must be named contents.lr and declare schema_version: 1.
No Raw HTML: HTML tags (<script>, <style>, <div>, etc.) are prohibited in text fields and Markdown bodies.
Approved Images: Attachments must be PNG, JPEG, or WebP files located within the record directory. Files must match their magic-byte signatures.
Limits: Up to 100 imported files, maximum 5 MiB per file, and maximum 20 MiB total per project snapshot.
Source Commits: Devlog source_commit values must be valid 40-character commit hashes existing on the branch history.
No Symlinks or Executables: Linked paths and executable scripts under .labyricorn/ are rejected.

Assistant Guidance (`AGENTS.md`)

This repository uses hierarchical AGENTS.md files to guide coding assistants:

AGENTS.md (Root): General project guidelines, authorization boundaries, and devlog practices.
.labyricorn/AGENTS.md: Publishing boundary contract and security rules.
.labyricorn/project/AGENTS.md: Rules for editing project exhibition metadata.
.labyricorn/devlog/AGENTS.md: Standards for crafting verifiable devlog entries.

Coding assistants working in this repository should always review the nearest applicable AGENTS.md before making changes.

License

This template is released into the public domain under the Unlicense.

README.md

Labyricorn Project Template