From 7c86455b9d6ed6ee1c13505cde6e55e11ebe9b5b Mon Sep 17 00:00:00 2001 From: Svjatoslav Agejenko Date: Thu, 25 Jun 2026 01:17:24 +0300 Subject: [PATCH] docs: add AGENTS.org with operating guide for this repo First cut. Covers: repo purpose, layout, conventions (capitalized directory names, per-page template, front matter, bullets, links), and procedure for adding a new project. Future commits can extend with: renaming procedure, workflow preferences, tooling notes, related skills, pitfalls. --- AGENTS.org | 123 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 123 insertions(+) create mode 100644 AGENTS.org diff --git a/AGENTS.org b/AGENTS.org new file mode 100644 index 0000000..d885060 --- /dev/null +++ b/AGENTS.org @@ -0,0 +1,123 @@ +#+TITLE: AGENTS — Operating guide for the physical repo + +* Purpose + +This repository catalogs hobby-scale physical designs (3D-printable +cases, mounts, organizers, optical adapters, small electronic +projects). Each design lives in its own subdirectory under one of four +top-level categories. + +The repo is a *publishing artifact*, not a buildable codebase. There +is no compiler, no test runner, no package manager. The deliverable is +HTML exported from Emacs / org-mode. + +* Layout + +| Path | Purpose | +|------------------+---------------------------------------------------| +| =index.org= | Landing page; lists every project with thumbnails | +| =style.css= | Shared stylesheet referenced by every page | +| =COPYING= | CC0 license text | +| =Cases/= | 10 projects — cases, covers, holders | +| =Furniture/= | 6 projects — furniture and mounts | +| =Miscellaneous/= | 13 projects — small electronics and tooling | +| =Optics/= | 4 projects — optical instruments and adapters | +| =Tools/= | Empty placeholder; future home for tool designs | +| =AGENTS.org= | This file | + +* Conventions + +** Every project directory starts with an uppercase letter + +A directory whose first character is lowercase is a bug. Fix with =git mv= via +a temporary sibling name on case-sensitive Linux: + +#+begin_example +git mv "old/name" "./.__rename_tmp_XXXX" +git mv "./.__rename_tmp_XXXX" "New/name" +#+end_example + +** Per-page section template + +Every =index.org= in a project directory follows this exact top-level +structure, in this order: + +1. =* Overview= (no =:PROPERTIES:= drawer, no =CUSTOM_ID=) + - The disclaimer bullet goes *first*, before any other content. + - All project content (images, paragraphs, download links, sub-sections + like =* Files=) flows directly under this heading. + +2. Optional middle sections such as =* Files=, =* Schematic=, =* Parts= + — these are content-only, not metadata. + +3. =* Repository= (last) + - License bullet (CC0, repo-scoped wording) + - Author block (name, homepage, mailto link) + - See-also list (other-physical-projects link + svjatoslav.eu/projects link) + - =** Git repository= sub-section with snapshot / gitweb / clone URL + +When adding a new page, copy an existing one and replace the body content. Do +not invent a new section layout — uniformity across pages matters for the +export pipeline. + +** Front matter (file header) + +Every page starts with this block, unchanged: + +#+begin_example +,#+SETUPFILE: ~/.emacs.d/org-styles/html/darksun.theme +,#+TITLE: +,#+LANGUAGE: en +,#+LATEX_HEADER: \usepackage[margin=1.0in]{geometry} +,#+LATEX_HEADER: \usepackage{parskip} +,#+LATEX_HEADER: \usepackage[none]{hyphenat} + +,#+OPTIONS: H:20 num:20 +,#+OPTIONS: author:nil + +,#+HTML_HEAD: + +[[file:../../index.html#outline-container-][Back to physical projects]] +#+end_example + +The back-link anchor must match the heading =CUSTOM_ID= of the corresponding +section in =index.org= (=outline-container-cases=, =outline-container-furniture=, +=outline-container-miscellaneous=, =outline-container-optics=, +=outline-container-cable-wire= for items under the "Cable, wire" subsection). + +** Bullet syntax + +In org-mode plain lists, =+=, =+=, and =*= are all interchangeable list markers +and render identically. Use =+= for top-level bullets in the =* Overview= and +=* Repository= sections to match the established style. Do not "fix" =+= +bullets to =-= or vice versa — they are equivalent. + +** Links + +- Internal project references in =index.org= use *URL-encoded* paths: + =[[file:Cases/Roll/index.html]]= becomes + =Cases/roll/index.html= → =Cases/Roll/index.html= in source. Spaces in + directory names are percent-encoded (=%20=). +- Cross-references between project pages use raw =file:= links with the + same encoding rules. +- The back-link in every page's front matter uses an HTML anchor fragment + pointing into =index.html=. + +* Adding a new project + +1. Pick a category directory (=Cases/=, =Furniture/=, =Miscellaneous/=, + =Optics/=, or =Tools/=). +2. Create a new subdirectory whose name starts with an uppercase letter. + Capitalize consistently with the rest of the category + (=Cases/Meiqqm portable dosimeter case/= style). +3. Copy the front matter block from any existing page in the same category, + adjusting the back-link anchor if the category outline structure has + changed. +4. Copy the =* Overview= + body + =* Repository= skeleton. Replace the body + content with the new project's images, text, and download links. +5. Add an entry to =index.org= under the correct category heading, using the + existing ~{{{imglnk(...)}}}~ macro pattern. Match the URL-encoding of + sibling entries (lower or upper first letter, percent-encoded spaces). +6. =git add= the new directory. Stage the =index.org= edit. Commit. +7. Regenerate the HTML locally with Emacs to verify the result. The HTML + itself stays untracked. -- 2.20.1