# Labyricorn Project Template

A starter template and baseline structure for projects compatible with
[Labyricorn](https://www.labyricorn.com).

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

```text
.
├── .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:

```ini
_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:

```ini
_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`:

```ini
_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:

```bash
python devlog_editor.py --validate
```

### Graphical Editor

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

```bash
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:

1. **Native Lektor Records**: Records must be named `contents.lr` and declare `schema_version: 1`.
2. **No Raw HTML**: HTML tags (`<script>`, `<style>`, `<div>`, etc.) are prohibited in text fields and Markdown bodies.
3. **Approved Images**: Attachments must be PNG, JPEG, or WebP files located within the record directory. Files must match their magic-byte signatures.
4. **Limits**: Up to 100 imported files, maximum 5 MiB per file, and maximum 20 MiB total per project snapshot.
5. **Source Commits**: Devlog `source_commit` values must be valid 40-character commit hashes existing on the branch history.
6. **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](LICENSE).