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.

diff --git a/AGENTS.org b/AGENTS.org
new file mode 100644 (file)
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: <Page 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: <link rel="stylesheet" href="../../style.css"/>
+
+[[file:../../index.html#outline-container-<category>][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.