Enhance documentation with contributing guidelines, planning docs, and agent policies

docs/ARCHITECTURE.md

@@ -0,0 +1,66 @@
+# FeDIY Architecture (Planning Baseline)
+
+This document captures current architectural intent. It is a planning artifact and should be refined as implementation decisions mature.
+
+## System Boundaries
+
+Primary system responsibilities:
+
+- Host and render DIY project content.
+- Manage local accounts and authorization.
+- Federate selected objects and activities using ActivityPub.
+- Enforce local moderation policy for both local and remote content.
+
+Out of scope for early phases:
+
+- Rich social graph features beyond project-oriented interactions.
+- Highly customized recommendation systems.
+
+## Core Domains
+
+- Identity and actors.
+- Project authoring and publishing.
+- Federation transport and protocol translation.
+- Moderation and trust policy.
+- Search and discovery.
+
+## Logical Components
+
+- API and web delivery layer.
+- Domain service layer for project and account workflows.
+- Federation layer (inbox/outbox, signing, verification, retries).
+- Persistence layer for local and federated records.
+- Moderation policy engine and audit log.
+- Background workers for delivery, indexing, and maintenance tasks.
+
+## Data and Object Strategy
+
+- Separate local canonical records from imported federated records.
+- Preserve source metadata for remote content and actor provenance.
+- Track object lifecycle states to support idempotent federation processing.
+
+## Federation Strategy
+
+- Start with a narrow, explicit ActivityPub profile.
+- Prefer strict validation and clear rejection reasons over permissive parsing.
+- Use replay-safe request validation and deterministic retry behavior.
+- Maintain an interop test matrix for protocol behaviors.
+
+## Moderation and Safety Strategy
+
+- Local policy is authoritative for what is visible on this instance.
+- Policy controls exist at three levels: object, actor, and instance.
+- Moderation actions produce auditable events.
+- Appeals and reversal policy should be documented before broad federation rollout.
+
+## Non-Functional Requirements
+
+- Reliability: resilient delivery and retry strategy for federated traffic.
+- Security: signature verification, key management, least-privilege defaults.
+- Performance: predictable latency for local reads and bounded queues for remote events.
+- Operability: metrics, logs, and runbooks for incident response.
+
+## Architecture Decision Practice
+
+- Capture major decisions with lightweight ADRs in a future docs/adrs directory.
+- Each ADR should include context, options considered, decision, and consequences.

docs/README.md

@@ -0,0 +1,9 @@
+# FeDIY Planning Docs
+
+This directory contains product and technical planning documents for FeDIY.
+
+- [Roadmap](ROADMAP.md): phased milestones from MVP to broader federation support.
+- [Architecture](ARCHITECTURE.md): system boundaries, components, and design constraints.
+- [Workflow](WORKFLOW.md): Red-Green TDD/BDD delivery model and GitHub Flow branching policy.
+
+These docs are intended to evolve as priorities change.

docs/ROADMAP.md

@@ -0,0 +1,95 @@
+# FeDIY Roadmap
+
+This roadmap prioritizes a usable core product first, then federation depth and community scaling.
+
+## Product Intention
+
+Build a federated DIY project-hosting platform in Rust, inspired by the utility of Ravelry and Instructables, but interoperable through ActivityPub.
+
+## Phase 0: Foundations
+
+Goals:
+
+- Stabilize development environment and reproducible tooling.
+- Define domain language and baseline architecture docs.
+- Establish quality process (TDD/BDD + GitHub Flow).
+
+Exit criteria:
+
+- Agreed glossary and architecture baseline.
+- Documented contribution and branch workflow.
+- CI skeleton in place for formatting, linting, and tests.
+
+## Phase 1: Single-Node MVP (No Federation Yet)
+
+Goals:
+
+- User identity and basic authentication model.
+- Core DIY project entities (project, materials, steps, media, tags).
+- Basic publishing lifecycle (draft, published, updated).
+- Search and browse within one instance.
+
+Exit criteria:
+
+- A user can publish and update a complete project end-to-end.
+- Project pages are discoverable and readable on one node.
+- Test coverage exists for core behavior paths.
+
+## Phase 2: ActivityPub Foundation
+
+Goals:
+
+- Implement canonical actor and object mapping.
+- Add outbox/inbox behavior for core project publication events.
+- Add HTTP Signatures and key lifecycle strategy.
+
+Exit criteria:
+
+- Instance can send and receive baseline ActivityPub messages for supported objects.
+- Signature validation and delivery retry logic are documented and tested.
+- Interop checks completed against at least one external implementation target.
+
+## Phase 3: Federation UX and Safety
+
+Goals:
+
+- Federation-aware project discovery and attribution.
+- Local moderation controls for remote content and actors.
+- Abuse-report and review workflow for moderators.
+
+Exit criteria:
+
+- Moderators can block/mute remote actors and instances.
+- Remote project visibility follows local moderation policy.
+- Audit trail exists for moderation decisions.
+
+## Phase 4: Community Scaling
+
+Goals:
+
+- Collaborative project patterns (forks/remixes, references, revisions).
+- Better onboarding, templates, and curation flows.
+- Operational hardening (backups, observability, incident playbooks).
+
+Exit criteria:
+
+- Multi-contributor workflows are clear and reliable.
+- Admin operations are documented with tested recovery drills.
+- Performance and reliability SLOs are defined and measured.
+
+## Moderation Model Milestones
+
+- Milestone A: Local content moderation for local users.
+- Milestone B: Remote actor and instance policy enforcement.
+- Milestone C: Transparent moderation history and appeals guidance.
+
+## Federation Strategy Milestones
+
+- Milestone A: Strictly scoped protocol subset with explicit compatibility statement.
+- Milestone B: Progressive support for richer activity types.
+- Milestone C: Interop matrix and periodic federation health review.
+
+## Review Cadence
+
+- Revisit priorities every 2 weeks.
+- Re-scope phases quarterly based on delivery and federation feedback.

docs/WORKFLOW.md

@@ -0,0 +1,57 @@
+# Development Workflow
+
+This project uses Red-Green TDD/BDD and GitHub Flow.
+
+## Red-Green TDD/BDD Cycle
+
+For each behavior increment:
+
+1. Red: describe behavior with a failing specification/test.
+2. Green: implement the smallest change needed to satisfy behavior.
+3. Refactor: improve structure while keeping behavior unchanged.
+
+BDD intent:
+
+- Express behavior in user-meaningful terms.
+- Prefer scenario-oriented acceptance criteria before implementation details.
+- Keep unit and integration tests aligned with documented behavior.
+
+Definition of done for a change:
+
+- Behavior is specified and verified.
+- Relevant tests are passing.
+- Refactoring has preserved behavior.
+- Documentation is updated when contracts or workflows change.
+
+## GitHub Flow Branching Policy
+
+Use short-lived branches from main.
+
+Branch pattern examples:
+
+- feature/<topic>
+- fix/<topic>
+- docs/<topic>
+- chore/<topic>
+
+Branch workflow:
+
+1. Create branch from latest main.
+2. Commit small, reviewable increments.
+3. Open pull request early.
+4. Keep branch current with main.
+5. Merge after review and checks pass.
+6. Delete merged branch.
+
+## Pull Request Expectations
+
+- Clear behavior statement and acceptance criteria.
+- Test evidence for the behavior change.
+- Notes on any architectural or moderation impact.
+- Scope limited to one cohesive change.
+
+## Agent Collaboration Rules
+
+- Agents may support test planning, scenario writing, and review checklists.
+- Agents must not generate executable core project code.
+- For implementation guidance, agents should link primary sources and provide paraphrased walkthroughs.