Initial commit

2026-08-23 21:17:53 -07:00
commit f077c83ec7
11 changed files with 2309 additions and 0 deletions
@@ -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
 *~
@@ -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.
@@ -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
 │   └── <optional image>
 └── devlog/
    ├── AGENTS.md
    ├── contents.lr
    └── <entry-slug>/
        ├── contents.lr
        └── <optional images>
 ```
 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.
@@ -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/<stable-slug>/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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -0,0 +1,24 @@
 This is free and unencumbered software released into the public domain.
 Anyone is free to copy, modify, publish, use, compile, sell, or
 distribute this software, either in source code form or as a compiled
 binary, for any purpose, commercial or non-commercial, and by any
 means.
 In jurisdictions that recognize copyright laws, the author or authors
 of this software dedicate any and all copyright interest in the
 software to the public domain. We make this dedication for the benefit
 of the public at large and to the detriment of our heirs and
 successors. We intend this dedication to be an overt act of
 relinquishment in perpetuity of all present and future rights to this
 software under copyright law.
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
 OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
 ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 OTHER DEALINGS IN THE SOFTWARE.
 For more information, please refer to <https://unlicense.org/>
@@ -0,0 +1,213 @@
 # 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).