Add scoped Labyricorn authoring guidance

2026-08-11 22:48:09 -07:00
parent feea2e67de
commit a4ad2ad10a
3 changed files with 160 additions and 0 deletions
@@ -0,0 +1,63 @@
 # 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 Thinkloom's exhibition page
  and development log on Labyricorn.
 - The Thinkloom repository is authoritative for this 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 communication
 - When the user says **discussion only**, do not edit files, run mutating
  commands, commit, push, request synchronization, or change external systems.
 - An implementation request authorizes only its clearly stated scope. Ask
  before changing project identity, content structure, schema, publication
  status, or synchronization behavior.
 - Do not commit or push unless the user explicitly requests it.
 - Before pushing, explain that the pushed publishing content may be imported
  into the public Labyricorn site.
 - Preserve unrelated and uncommitted work. Never discard changes to obtain a
  clean worktree.
 ## Content contract
 - Use native Lektor records named `contents.lr`.
 - Preserve `schema_version: 1` until a coordinated schema migration is approved
  in both the project and Labyricorn site repositories.
 - Do not add templates, models, plugins, workflows, executable files, generated
  builds, or application state below `.labyricorn/`.
 - Keep attachments inside the record subtree that owns them.
 - Use UTF-8 text, `YYYY-MM-DD` dates, and stable lowercase hyphenated slugs.
 - Do not use raw HTML, scripts, embedded credentials, or active third-party
  content in Markdown fields.
 - Treat published URLs as durable. Ask before renaming or removing a published
  record; redirects or archival behavior may be required first.
 ## Security and synchronization
 - Never store or print passwords, API tokens, refresh credentials, private keys,
  `.netrc` contents, or other secrets in this directory.
 - Never place a refresh credential in a URL, query string, tracked script, or
  command example.
 - Do not claim that content is public merely because a push succeeded. Report
  push status and synchronization/publication status separately.
 - When an authenticated refresh mechanism is implemented and documented, use
  only its approved wrapper command and request at most one refresh for a pushed
  commit. Until then, do not invent or bypass a trigger mechanism.
 ## Validation and handoff
 - Parse every changed `contents.lr` file with Lektor's native record parser.
 - Confirm required fields are present and referenced source commits exist.
 - Run `git diff --check` and review the exact diff before committing.
 - At handoff, report changed publishing records, validation performed, commit
  and push status, and synchronization status if known.
@@ -0,0 +1,54 @@
 # Instructions for the Thinkloom development log
 These instructions supplement `.labyricorn/AGENTS.md` and apply to the
 `devlog/` directory.
 ## Index and entry structure
 - Keep the devlog index at `devlog/contents.lr` using `_model: devlog`.
 - Store each published entry at `devlog/<stable-slug>/contents.lr` using
  `_model: devlog-entry`.
 - Use a lowercase hyphenated directory name that describes the milestone. The
  directory name becomes part of the public URL and must remain stable.
 - Every entry must include `schema_version`, `title`, `date`, `author`,
  `summary`, `tags`, `source_commit`, and `body`.
 - Set `source_commit` to the full 40-character commit ID most directly
  associated with the entry. Confirm that it resolves in this repository.
 - Use the commit's actual calendar date for retrospective entries. Do not use
  the date on which the devlog prose was written.
 ## Editorial guidance
 - Base retrospective entries on verifiable repository history, existing project
  documents, and implemented behavior.
 - Do not invent motivations, conversations, results, release status, user
  feedback, or completion claims.
 - A devlog should explain the milestone, why it mattered, and what changed. It
  should not merely expand a commit message or enumerate every changed file.
 - Distinguish a design or schema contract from a completed runtime
  implementation.
 - Keep one main milestone per entry. Link to the relevant canonical commit using
  the Gitea HTTPS URL.
 - Write summaries that work in chronological listings without requiring the
  reader to open the entry.
 - Use focused tags consistently; avoid creating capitalization or spelling
  variants of an existing tag without a reason.
 ## Chronology and lifecycle
 - The Labyricorn site orders entries by `date` and provides links back to the
  project and to older/newer entries. Do not add manual next/previous links.
 - Multiple entries may share a date; ordering ties should be resolved by the
  importer from source history rather than invented timestamps in prose.
 - Do not rewrite old entries merely because the implementation later changed.
  Add a new entry or a clearly labelled correction when historical context is
  needed.
 - Do not delete or rename a published entry without explicit approval and a
  redirect or archival decision for its existing URL.
 ## Review requirements
 - Verify the entry date and `source_commit` against `git log`.
 - Check that the source-commit link targets the same full commit ID.
 - Check prose against the referenced commit and current documentation.
 - Parse the record with Lektor and run `git diff --check` before committing.
@@ -0,0 +1,43 @@
 # Instructions for the Thinkloom exhibition 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`.
 - Keep `project_id: thinkloom` stable. It is the durable identity used by the
  Labyricorn importer and public URL.
 - Keep the repository URL pointed at the canonical Thinkloom source repository.
  Ask before changing the repository, default branch, project status, author,
  or start date.
 - Store project-owned visual attachments in this directory and reference them
  by filename from `contents.lr`.
 - Use descriptive, web-appropriate alternative text whenever the content schema
  introduces images that require it.
 ## Editorial guidance
 - Write the exhibition page as a concise project narrative, not as a copy of
  `README.md` and not as release documentation.
 - Verify technical and status claims against the current repository before
  editing them.
 - Distinguish completed work, formal design work, experimental work, and future
  work. Do not imply implementation or conformance that the repository does not
  support.
 - Preserve Thinkloom's established product boundaries: native, local-first,
  user-controlled, preview-first model assistance, and no hosted browser
  companion unless the project itself explicitly changes those boundaries.
 - Do not manually add latest-commit, README, license, language, release, issue,
  or other repository-derived metadata to the body. The Labyricorn importer and
  repository information card own those values.
 - Keep the summary suitable for project listings and social previews. Keep the
  body useful to visitors who want to understand the project rather than build
  it.
 ## Review requirements
 - Check that `logo` and other attachment references resolve within `project/`.
 - Check that Markdown links are intentional and use HTTPS.
 - Re-read the rendered prose for unsupported claims before committing.