feat: Enhance documentation and workflow clarity; add CI configuration for automated checks

2026-05-23 18:30:44 -05:00
parent 2ecab4db12
commit 36c4ed7b62
6 changed files with 67 additions and 35 deletions
@@ -46,12 +46,16 @@ Current product definition:
 - Core project structure includes materials/ingredients, required tools, and ordered step-by-step instructions.
 - Steps may include embedded media hosted on this instance or linked from external sources.
 - Projects may include external canonical links (for example homepage, repository, or source publication).
+- Projects may include multiple typed canonical links (for example homepage, repository, build instructions, video walkthrough, or source publication). Canonical links are project-scoped by default and remain stable across revisions; version-scoped links are allowed when a specific published revision needs its own artifact or source reference.
 - Explicit project versioning is preferred and will be part of the domain model.
 - The project model is composable: a minimal core plus optional domain-specific extensions.
 - Domain-specific detail (for example knitting patterns/yarns, 3D print profiles/STLs, electronics BoM data) should be representable without being mandatory for all instances.
 - First-party FeDIY focuses on a stable extension mechanism rather than implementing every niche schema directly.
- Materials are also an extensible entity: the core material record captures display name, quantity, and unit; domain-specific attributes (yarn weight, fibre content, filament diameter/material, wood species/grade, electronics component value/package) are carried in extension payloads on the material entry, using the same extension mechanism as project-level extensions.
+- Materials are project-scoped entries with a fixed core shape: display name, structured quantity, unit, and optional note. Material entries are embedded within a project revision rather than modeled as independent top-level entities in Phase 1. Each material entry can carry the same extension payload mechanism as project-level extensions for domain-specific attributes (yarn weight, fibre content, filament diameter/material, wood species/grade, electronics component value/package).
+- Material extensions use the same typed JSON block model as project extensions: namespace, type identifier, version, and payload. Clients discover available material extensions from explicit material-entry metadata. Known blocks are schema-validated; unknown optional blocks are preserved and round-tripped; unknown required blocks can be rejected until the instance supports them.
+- Required tools are project-scoped entries with a lightweight core shape: display name and optional note. Tools are embedded within a project revision rather than modeled as independent top-level entities in Phase 1. Each tool entry can carry optional metadata such as skill level, safety notes, and alternatives. A shared tool taxonomy is a future option, not a Phase 1 requirement.
 - A federated material catalog is a long-term goal: community-defined material types and shared taxonomy entries could be federated as ActivityPub objects, allowing instances to reference a common vocabulary without requiring central authority.
+- Project-level extensions are stored as typed JSON blocks on the revision, each with a namespace, type identifier, version, and payload. Namespaces should be collision-resistant (for example reverse-DNS or URL-based identifiers). Clients discover available extensions from explicit revision metadata. Known extension blocks are schema-validated; unknown optional blocks are preserved and round-tripped; unknown required blocks can be rejected until the instance supports them.

 ### Project Revision Lifecycle