From bdcc2264ad9be0ba633942f321c9a73159ab4e85 Mon Sep 17 00:00:00 2001 From: Labyricorn Date: Sun, 23 Aug 2026 21:13:48 -0700 Subject: [PATCH] Initialize Labyricorn project publishing records, assistant instructions, and devlog editor --- .gitignore | 23 + .labyricorn/AGENTS.md | 42 + .labyricorn/README.md | 38 + .labyricorn/devlog/AGENTS.md | 57 + .labyricorn/devlog/contents.lr | 7 + .labyricorn/project/AGENTS.md | 33 + .labyricorn/project/contents.lr | 27 + AGENTS.md | 48 + README.md | 214 +++- devlog_editor.py | 1797 +++++++++++++++++++++++++++++++ 10 files changed, 2282 insertions(+), 4 deletions(-) create mode 100644 .gitignore create mode 100644 .labyricorn/AGENTS.md create mode 100644 .labyricorn/README.md create mode 100644 .labyricorn/devlog/AGENTS.md create mode 100644 .labyricorn/devlog/contents.lr create mode 100644 .labyricorn/project/AGENTS.md create mode 100644 .labyricorn/project/contents.lr create mode 100644 AGENTS.md create mode 100644 devlog_editor.py diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..5b0ed67 --- /dev/null +++ b/.gitignore @@ -0,0 +1,23 @@ +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] +*.class + +# Environments +.venv/ +env/ +venv/ +ENV/ + +# Caches and builds +.cache/ +build/ +dist/ + +# Operating system files +.DS_Store +Thumbs.db + +# Temporary and editor files +*.swp +*~ \ No newline at end of file diff --git a/.labyricorn/AGENTS.md b/.labyricorn/AGENTS.md new file mode 100644 index 0000000..06d4668 --- /dev/null +++ b/.labyricorn/AGENTS.md @@ -0,0 +1,42 @@ +# Instructions for Labyricorn publishing content + +These instructions apply to the entire `.labyricorn/` directory. More specific +instructions in `project/AGENTS.md` and `devlog/AGENTS.md` also apply within +those directories. + +## Purpose and ownership + +- This directory is the repository-owned source for the project's exhibition + page and development log on Labyricorn. +- This project repository is authoritative for the content. The Labyricorn site + imports it as read-only content. +- Read `.labyricorn/README.md` and the nearest scoped `AGENTS.md` before editing + a publishing record. +- Keep publishing changes focused. Do not alter application code merely to + support an exhibition or devlog edit unless the user separately requests it. + +## Authorization and content contract + +- Preserve unrelated and uncommitted work. Never discard changes to obtain a + clean working tree. +- Do not commit or push unless the user explicitly requests publication. +- Use native Lektor records named `contents.lr` and preserve `schema_version: 1` + until a coordinated schema migration is approved. +- Keep attachments inside the record subtree that owns them. +- Use UTF-8 text, `YYYY-MM-DD` dates, and stable lowercase hyphenated slugs. +- Do not add templates, models, plugins, workflows, executable files, builds, + application state, credentials, raw HTML, scripts, or active third-party + content below `.labyricorn/`. +- Treat published URLs as durable. Ask before renaming or removing a published + record; redirects or archival behavior may be required first. + +## Security, synchronization, and review + +- Never store or print passwords, API tokens, refresh credentials, private keys, + `.netrc` contents, or other secrets in this directory. +- Do not claim content is public merely because a push succeeded. Report push + status and Labyricorn synchronization status separately. +- Parse changed records, confirm referenced source commits exist, run + `git diff --check`, and review the exact publishing diff before committing. +- At handoff, report changed publishing records, validation performed, commit + and push status, and synchronization status if known. \ No newline at end of file diff --git a/.labyricorn/README.md b/.labyricorn/README.md new file mode 100644 index 0000000..4c58b74 --- /dev/null +++ b/.labyricorn/README.md @@ -0,0 +1,38 @@ +# Labyricorn publishing content + +This directory is the repository-owned source for this project's exhibition +and development log on Labyricorn. The project repository remains the source +of truth; the Labyricorn site imports this content as read-only. + +The content uses native Lektor records: + +```text +.labyricorn/ +├── AGENTS.md +├── README.md +├── project/ +│ ├── AGENTS.md +│ ├── contents.lr +│ └── +└── devlog/ + ├── AGENTS.md + ├── contents.lr + └── / + ├── contents.lr + └── +``` + +Rules: + +- `project/contents.lr` uses the `project` model. +- `devlog/contents.lr` uses the `devlog` model. +- Each entry is a directory below `devlog/` containing a `contents.lr` record + using the `devlog-entry` model. +- Entry directory names are stable public slugs. Do not rename a published entry + without arranging a redirect on the Labyricorn site. +- Dates use `YYYY-MM-DD`; `source_commit` uses the full relevant commit ID. +- Publishing attachments stay inside the record subtree that owns them. +- Do not put credentials, builds, application state, or executable code here. + +Editing these records does not itself prove that the public site synchronized. +Report repository publication and Labyricorn synchronization separately. \ No newline at end of file diff --git a/.labyricorn/devlog/AGENTS.md b/.labyricorn/devlog/AGENTS.md new file mode 100644 index 0000000..8e4b976 --- /dev/null +++ b/.labyricorn/devlog/AGENTS.md @@ -0,0 +1,57 @@ +# Instructions for the Labyricorn development log + +These instructions apply to `.labyricorn/devlog/` and help coding assistants +maintain the project's public development narrative safely. + +## Format and ownership + +- Keep the devlog index at `devlog/contents.lr` using `_model: devlog` and + `schema_version: 1`. +- Store each entry at `devlog//contents.lr` using + `_model: devlog-entry` and `schema_version: 1`. +- Use lowercase hyphenated entry slugs. Published slugs are durable public URLs; + do not rename or delete them without explicit approval and a redirect or + archival decision. +- Every entry must contain `title`, `date`, `author`, `summary`, `tags`, + `source_commit`, and Markdown `body` fields. +- Keep entry attachments in that entry's directory. Only PNG, JPEG, and WebP + images are accepted by the Labyricorn importer. +- Do not add templates, models, plugins, executable code, builds, application + state, credentials, or active third-party content below this directory. + +## Content guidance + +- Base entries on verifiable repository history, project documentation, and + implemented behavior. Do not invent motivations, results, release status, + user feedback, or completion claims. +- Explain the milestone, why it mattered, and what changed. Keep one main + milestone per entry and write a summary that works in a chronological list. + Do not merely expand a commit message or enumerate every changed file. +- Distinguish design and schema contracts from completed runtime behavior. +- Link to the relevant canonical commit using the repository's HTTPS web URL. +- Use the referenced commit's actual `YYYY-MM-DD` calendar date for retrospective + entries, not the date on which the prose was drafted. +- Set `source_commit` to the full lowercase 40-character commit ID most directly + associated with the milestone. It must be an ancestor of the published branch. +- Topics are comma-separated display labels. Unknown topics are allowed: the + site keeps them visible but unlinked. Do not create or edit the site's tracked + tag registry from this project repository. +- Use Markdown without raw HTML, scripts, embedded credentials, or active + external content. +- Multiple entries may share a date. The site resolves ties from source history; + do not invent timestamps or manual next/previous links. +- Do not rewrite older entries merely because the implementation later changed. + Add a new entry or a clearly labelled correction when historical context is + needed. + +## Safety and review + +- Preserve unrelated project files and uncommitted work. The devlog owns only + `.labyricorn/devlog/`. +- Do not commit or push unless the user explicitly requests publication. +- Before publication, verify claims against the referenced commit, validate all + records, check that the source-commit link uses the same full commit ID, review + the exact devlog diff, and confirm unrelated files are not staged in the + publishing commit. +- Prefer the repository-root `devlog_editor.py` for routine validation and safe + publication when it is available. \ No newline at end of file diff --git a/.labyricorn/devlog/contents.lr b/.labyricorn/devlog/contents.lr new file mode 100644 index 0000000..164045c --- /dev/null +++ b/.labyricorn/devlog/contents.lr @@ -0,0 +1,7 @@ +_model: devlog +--- +schema_version: 1 +--- +title: Labyricorn Project Template development log +--- +summary: Milestones and development log entries for the Labyricorn project template. \ No newline at end of file diff --git a/.labyricorn/project/AGENTS.md b/.labyricorn/project/AGENTS.md new file mode 100644 index 0000000..b6dc3d9 --- /dev/null +++ b/.labyricorn/project/AGENTS.md @@ -0,0 +1,33 @@ +# Instructions for the Labyricorn project record + +These instructions supplement `.labyricorn/AGENTS.md` and apply to the +`project/` directory. + +## Record structure + +- Maintain exactly one project record at `project/contents.lr` using + `_model: project` and `schema_version: 1`. +- Keep `project_id` stable. It is the durable identity used by the importer and + public URL. +- Ask before changing the repository URL, default branch, project status, + author, start date, or project identity. +- Store project-owned images in this directory and reference them by filename + from `contents.lr`. Only PNG, JPEG, and WebP images are accepted. + +## Editorial guidance + +- Write the exhibition page as a concise project narrative, not as a copy of + the repository README or as release documentation. +- Verify technical and status claims against the repository before editing. +- Distinguish completed work, formal design work, experiments, and future work. +- Do not manually add repository-derived commit, license, language, release, + issue, star, or fork metadata. The Labyricorn importer owns those values. +- Keep the summary suitable for listings and social previews. + +## Review requirements + +- Confirm all required project fields are present and any image reference stays + inside `project/`. +- Check Markdown links are intentional HTTPS links and prose makes no unsupported + claims. +- Validate the record and run `git diff --check` before committing. \ No newline at end of file diff --git a/.labyricorn/project/contents.lr b/.labyricorn/project/contents.lr new file mode 100644 index 0000000..d0b5ff6 --- /dev/null +++ b/.labyricorn/project/contents.lr @@ -0,0 +1,27 @@ +_model: project +--- +schema_version: 1 +--- +project_id: labyricorn-project-template +--- +title: Labyricorn Project Template +--- +summary: + +Initial template and publishing structure for Labyricorn-compatible projects and development logs. +--- +status: active +--- +started: 2026-08-23 +--- +author: Labyricorn +--- +repository_url: https://git.labyricorn.com/Labyricorn/labyricorn-project-template +--- +default_branch: main +--- +tags: template, lektor, python +--- +body: + +Starter template providing the standard .labyricorn/ publishing records, assistant instructions, devlog structure, and repository tooling for publication on Labyricorn. \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..1740954 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,48 @@ +# Instructions for coding assistants + +These instructions apply to this repository. Read `README.md` and the relevant +scoped `AGENTS.md` files before making changes. + +## Communication and authorization + +- Do not assume the user's desired behavior, architecture, or content structure + when the answer would materially affect the result. +- When the user requests discussion or review, do not edit files, run mutating + commands, commit, or push. +- An implementation request authorizes work only within its clearly stated + scope. Routine steps within that scope may proceed, but confirm before + expanding scope or making irreversible choices. +- Before implementation, state the intended files and systems to be changed. +- Do not commit or push unless the user explicitly requests it. +- Preserve unrelated edits and uncommitted work. Never discard changes merely + to obtain a clean working tree. + +## Project and publishing boundaries + +- Application and project source code lives at the repository root and normal + subdirectories. +- The `.labyricorn/` directory is the repository-owned source for project + exhibition records and development logs published on Labyricorn. +- Keep publishing records in `.labyricorn/` aligned with actual repository + implementation and history. +- Read `.labyricorn/AGENTS.md`, `.labyricorn/project/AGENTS.md`, and + `.labyricorn/devlog/AGENTS.md` when modifying publishing records. + +## Content contract and devlog practices + +- Use native Lektor records named `contents.lr` with `schema_version: 1`. +- Keep attachments inside the record subtree that owns them (PNG, JPEG, WebP). +- Do not introduce raw HTML, scripts, executable files, builds, or credentials + below `.labyricorn/`. +- For devlog entries, base records on verifiable repository commits and history. + Set `source_commit` to the full 40-character commit ID on the branch. +- Devlog dates should reflect the commit's calendar date (`YYYY-MM-DD`). + +## Validation and review + +- Run `python devlog_editor.py --validate` to verify that `.labyricorn/` records, + project identity, devlog index, and devlog entries adhere to the schema. +- Alternatively, launch the graphical editor with `python devlog_editor.py` for + interactive management of devlog entries and publishing status. +- Run `git diff --check` and review diffs carefully before staging or committing. +- At handoff, summarize files changed, validation performed, and any next steps. \ No newline at end of file diff --git a/README.md b/README.md index 7a8c2c8..775887c 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,213 @@ -# labyricorn-project-template +# Labyricorn Project Template -Included AGENTS.md files, initial Lektor files and file system +A starter template and baseline structure for projects compatible with +[Labyricorn](https://www.labyricorn.com). -To the acting agent. Read this file then replace all existing text in the README.md with proper documentation. You do not need to retain this text or instructions afterward. +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. -Setup the workspace to act as an initial labyricorn.com compatible project with devlogs. You can find the needed documentation at: https://git.labyricorn.com/OpenAI/labyricorn-site \ No newline at end of file +--- + +## 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 +│ │ └── # Project logo (PNG, JPEG, WebP) +│ └── devlog/ +│ ├── AGENTS.md # Instructions for devlog records +│ ├── contents.lr # Devlog index record +│ └── / # (Optional) Devlog entry directories +│ ├── contents.lr # Devlog entry record +│ └── # 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//` +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 (`