feat: add regenerate-agent-graph workflow and reorganize docs structure

[artcava]

Overview

This issue tracks two related improvements to the XPoster repository:

1. A new GitHub Actions workflow to automatically regenerate a graphify-dotnet knowledge graph on every merge to develop.
2. A reorganization of the docs/ folder into logical subdirectories to improve navigability for both humans and LLM agents.

---

Part 1 — Regenerate Agent Graph Workflow

What

Add .github/workflows/regenerate-agent-graph.yml: a dedicated GitHub Actions workflow that runs graphify-dotnet on the full repository after every PR merge into develop, stores the output in docs/agent-graph/, and commits it back automatically.

Why

XPoster already uses LLM-assisted development (.github/copilot-instructions.md, .github/agents/, .github/skills/). A continuously updated knowledge graph gives any AI coding assistant a persistent, structured view of the codebase and documentation without requiring full re-indexing on every session.

Rationale for key design choices

Choice	Reason
graphify-dotnet over Python graphifyy	XPoster is exclusively .NET 8. Using a dotnet tool keeps the CI toolchain uniform and avoids introducing a Python runtime dependency.
Trigger: pull_request + types: [closed] + merged == true	Regenerates the graph once per actual merge, not on every commit on a feature branch. Avoids redundant runs.
workflow_dispatch as secondary trigger	Allows manual recovery if the graph gets out of sync.
concurrency with cancel-in-progress: true	Prevents redundant queued runs if multiple PRs are merged in quick succession.
fetch-depth: 0	Ensures graphify-dotnet has full Git history context for richer graph edges.
Output path docs/agent-graph/	Keeps the graph versioned alongside documentation, making it visible in PRs and accessible to agents browsing the repo.
--format wiki,report,json	Produces three complementary views: wiki (human-readable), report (summary), JSON (machine-readable for agents).
Conditional commit + [skip ci]	Commits only when the graph actually changes. The [skip ci] tag prevents a CI re-trigger loop.
NOTICE.md auto-generated in docs/agent-graph/	Provides explicit semantic metadata for LLMs: distinguishes code nodes (src/, tests/) from documentation nodes (docs/) and infrastructure nodes (infra/). Documentation nodes contain natural language text only — not executable code.

Acceptance criteria

• .github/workflows/regenerate-agent-graph.yml added to develop
• Workflow triggers correctly on PR merge to develop
• docs/agent-graph/ is created and committed after first run
• docs/agent-graph/NOTICE.md is generated with correct content type annotations
• No CI loop triggered by the auto-commit

---

Part 2 — Docs Reorganization

What

Reorganize the flat docs/ directory into logical subdirectories that reflect document purpose and audience.

Why

The current docs/ folder contains 12+ files at the same level with no grouping. As the project grows, discoverability degrades for both developers and AI agents. Grouping by purpose makes navigation faster and allows agents (and graphify) to infer context from path alone.

Proposed structure

docs/
├── agent-graph/          ← graphify output (generated, do not edit manually)
│   └── NOTICE.md
├── setup/                ← provider-specific setup guides
│   ├── setup-azure-foundry.md
│   ├── setup-deepseek.md
│   ├── setup-falai.md
│   └── setup-openai.md
├── architecture.md       ← system design (root level: primary reference)
├── configuration.md      ← runtime configuration reference
├── deployment.md         ← deployment procedures
├── extending-xposter.md  ← developer extension guide
├── getting-started.md    ← onboarding entry point
├── index.md              ← docs index/TOC
├── monitoring.md         ← observability and monitoring
└── analysis/             ← research and decision records (ADR-like)
    └── analysis-linkedin-token-auto-refresh.md

Rationale

• docs/setup/: all setup-*.md files share a common pattern (provider-specific integration instructions). Grouping them signals to agents and humans alike that these are configuration guides, not architecture or operational docs.
• docs/analysis/: analysis documents are decision records and research outputs, not operational guides. Separating them prevents confusion with normative documentation.
• Root-level docs kept flat: architecture.md, configuration.md, deployment.md, extending-xposter.md, getting-started.md, index.md, monitoring.md are primary reference documents that benefit from being directly accessible without a subdirectory hop.
• docs/agent-graph/ reserved for generated output: never edited manually, clearly separated from human-authored content.

Acceptance criteria

• All setup-*.md files moved to docs/setup/
• analysis-linkedin-token-auto-refresh.md moved to docs/analysis/
• docs/index.md updated to reflect new paths
• Internal cross-references in docs updated if any
• graphify-dotnet NOTICE.md updated to reflect new doc paths

---

Implementation order

1. Add regenerate-agent-graph.yml workflow (Part 1)
2. Reorganize docs/ structure (Part 2)
3. Update NOTICE.md template in the workflow to reflect final doc paths
4. Open PR to develop

[github-actions]

👋 Thanks for opening this issue! A maintainer will review it soon and label it as approved if it can proceed to development.