Grid Placement

GridPlacement Docs Organization Pattern

Goal

Keep docs:

  • Easy to navigate (low cognitive load)
  • Low duplication / low maintenance
  • Aligned with the project policy: 5.1 is the current stable GDScript line and 6.0 is C#-first

Placement rules (where docs live)

  • Plugin-local docs for GridPlacement belong under:
    • plugins/gameplay/GridPlacement/docs/**
  • Workspace-wide standards and published docs live under:
    • /home/chris/game_dev/docs/**
  • Tooling docs live under:
    • toolkits/cs/docs/**
  • GridPlacement docs must not live under toolkits/cs/**.

Pattern (Hybrid)

1) Canonical = layer/topic-first

Most docs should live in layer/topic folders:

  • Core/ — C# core architecture, services, test strategy
  • Godot/ — engine-facing adapters and boundary notes
  • Migration/ — migration priorities/status
  • Roadmap/ — roadmap and production readiness
  • design/ — local feature design notes
  • gdscript/ — legacy addon docs + GDScript-specific notes
  • reports/ — generated outputs (coverage/health/etc.)
  • _archive/ — historical docs only

2) Version folders = entrypoints only

Use these for navigation, not for duplicating full doc trees:

  • 5.1/README.md — entrypoint for the 5.1 GDScript maintenance line
  • 6.0/README.md — entrypoint for the 6.0 C#-first line

Version folders may also host strictly version-specific docs when there is no good home elsewhere.

Naming rules

  • Prefer short, explicit names.
  • Prefer README.md as an entrypoint to a folder.
  • Prefer “topic” names inside layer folders (e.g. C_SHARP_EDITOR_RUNTIME_BOUNDARY.md).

GDScript constants placement rules

  • Resource paths / preloads: use gdscript/grid_building/core/gb_constants.gd (legacy). This file is treated as deprecated and should not be expanded except for maintaining existing path/preload constants.
  • String keys / identifiers (dictionary keys, schema/version strings, feedback keys, group names): use gdscript/grid_building/core/gb_keys.gd.
  • Why: keeps resource/path concerns separate from protocol-like identifiers, and avoids adding new usage to deprecated GBConstants.

When to create a version-specific doc

Create a doc under 5.1/ or 6.0/ only when:

  • The behavior is clearly version-bounded, AND
  • Placing it under Core/ or Godot/ would mislead readers into thinking it applies to both tracks.

Otherwise, keep the doc in the canonical layer folder and mention version notes inside it.

Archive rules

  • _archive/ is reference-only.
  • If a doc is obsolete but historically useful, move it to _archive/ and add a short “obsolete / replaced by” note at the top.