Update vault configuration

AGENTS.md

@@ -4,31 +4,93 @@ This repository stores agent-generated artifacts across projects.
 
 ## Layout
 
-- Use `projects/` for project-specific artifacts.
-- Use `projects/<project>/...` where `<project>` is the lowercase basename of the project directory.
-- Use project-specific subdirectories such as `spec/`, `tasks/`, or `adr/` when appropriate.
-- Treat that list as examples, not as an exhaustive or required taxonomy.
+- Use `projects/<project>/` for project-specific artifacts, where `<project>` is the lowercase basename of the project directory.
+- Keep every project directory flat.
+  Do not create artifact-type or effort subdirectories.
+- Store an artifact's attachments beside its Markdown note.
 - Use `wiki/` for cross-project Markdown knowledge entries.
 - Do not write to `wiki/` unless the user explicitly instructs you to do so through a dedicated skill.
 - Keep `wiki/` flat.
 - Do not create subdirectories under `wiki/`.
-- Use `tags/` for Markdown tag files.
+- Use `tags/` for Tags.
 - Keep `tags/` flat.
 - Do not create subdirectories under `tags/`.
 - Do not create `.gitkeep` files.
 - Keep user-facing top-level artifact directories limited to `projects/`, `wiki/`, and `tags/`.
 - Hidden tool directories such as `.git/` and `.obsidian/` are allowed.
 
-## Tags
+## Naming conventions
 
-- Tag files exist only to form clusters in the Obsidian graph view.
-- Keep tag files free of semantic content.
-- A trailing newline is acceptable.
-- Link to tag files with explicit Obsidian wikilinks, such as `[[tags/example]]`.
-- For project-specific artifacts, when they use tag links, place them on a compact first line.
+### Global filename rules
+
+- File names must be lowercase unless an established tool convention requires otherwise.
+- Spaces are allowed unless a location-specific rule says otherwise.
+
+### `projects/`
+
+- Name each Markdown artifact `<NNN>-<scope-slug>[-<subject-slug>]-<artifact-type>.md`.
+- `NNN` is the next value after `.counter`.
+- Pad `NNN` to at least three digits and expand naturally after `999`.
+- Use the project slug as the scope slug for project-wide artifacts.
+- Use the effort slug as the scope slug for effort-scoped artifacts.
+- Do not use subsystem or topic slugs as scope slugs.
+- Use the optional subject slug to distinguish multiple artifacts of one type within a scope.
+- Use slugs for `scope-slug`, `subject-slug`, and `artifact-type`.
+  Slugs are lowercase and use hyphens instead of spaces.
+- Let the creating skill define its artifact-type slug.
+  There is no vault-wide type registry.
+- Name a project's context artifact `<NNN>-<project-slug>-context.md`.
+- Name each attachment from its owning artifact's complete stem plus a numeric suffix, such as `042-wayfinder-layout-prototype-01.png`.
+  Attachments do not receive their own identifiers.
+- Preserve an artifact's identifier when renaming its other filename components.
+- Update every wikilink to a renamed artifact in the same change.
+
+### `wiki/`
+
+- Name each wiki entry with a lowercase human-readable filename.
+- Spaces are allowed.
+- Do not use artifact identifiers in wiki entry filenames.
+- Do not apply project artifact naming rules to wiki entries.
+
+### `tags/`
+
+- Name each Tag with a lowercase tag name.
+- Spaces are allowed.
+- Do not use artifact identifiers in Tag filenames.
+
+## Identifier allocation
+
+- `.counter` at the vault root is the tracked source of the most recently allocated identifier.
+- To allocate an identifier, increment `.counter` and persist it before creating the artifact.
+- Never reuse an allocated identifier, including after failed creation or deletion.
+- Do not lock `.counter`.
+- After parallel creation, the coordinating agent must find duplicate identifiers, preserve pre-existing artifacts, renumber its current outputs, update their wikilinks, and advance `.counter` as needed.
+
+## Metadata and links
+
+- Store machine-readable artifact metadata in YAML frontmatter.
+- Store Obsidian wikilinks in YAML as quoted text or quoted list values.
+- Use a singular `parent` property for the earlier artifact that directly caused the current artifact to exist.
+- Use a `blocked-by` list for zero or more upstream artifacts that must resolve before the current artifact can be acted on.
+- Use bare wikilinks without display aliases.
+
+## Hashtags and Tags
+
+- Use Obsidian hashtags for note metadata through the YAML `tags` property.
+- A Tag is a content-free Markdown note under `tags/` used only to form clusters in the Obsidian graph view.
+- A trailing newline in a Tag is acceptable.
+- Link to Tags with bare Obsidian wikilinks, such as `[[example]]`.
 - Do not define the internal structure of wiki entries yet.
 
 ## Gotchas
 
 - Do not apply project-specific artifact structure rules to wiki entries.
 Wiki entry structure is intentionally undecided.
+- Context artifacts under `projects/` are normal identifier-bearing project artifacts.
+They use the next value after `.counter`, not a reserved `000` prefix.
+- Do not invent naming conventions for new directories.
+The vault layout is fixed unless the user explicitly changes it.
+- Wayfinder map artifacts under `projects/` still need the normal artifact-type suffix.
+Use `-map.md`, not a filename that ends at the effort slug.
+- Preserve `blocked-by` dependency links after blockers resolve.
+Do not remove entries merely because a dependency is no longer actively blocking the next action.