Skip to content

docs: refresh README, user guide, architecture, and templates for v1.6#7

Merged
giftedloser merged 5 commits into
mainfrom
codex/docs-userguide-repo-polish
May 2, 2026
Merged

docs: refresh README, user guide, architecture, and templates for v1.6#7
giftedloser merged 5 commits into
mainfrom
codex/docs-userguide-repo-polish

Conversation

@giftedloser
Copy link
Copy Markdown
Owner

Summary

Documentation and repo hygiene pass to align user-facing docs with the
v1.6 Runway app (first-run setup, sync status pill, Tags view + drawer,
Provisioning Builder, Build Payload availability states, EntityPicker
for Change Primary User, single-device destructive actions, deep-linked
tabbed device detail). No product features added; no package version
bump; no main push.

Docs changed

  • README.md — replaced stale "1.0 Readiness" with a tenant testing
    warning; expanded "What it does" with first-run setup, sync pill,
    Tags, Provisioning Builder, Build Payload, EntityPicker, centralised
    portal links, custom-rule preview; added "What it intentionally does
    not do".
  • docs/user-guide.md — end-to-end rewrite. New sections: first-run
    setup, sync status pill, Tags view + drawer, Provisioning Builder
    workflow, Build Payload panel + availability states, EntityPicker
    primary-user search, tabbed device detail (Identity/Targeting/
    Enrollment/Drift/Operate/History) with ?tab= deep-links, tenant
    testing workflow.
  • docs/architecture.md — added app-only vs delegated split, first-run
    completion criteria, sync status source of truth, tag_config cleanup
    notes, raw_graph_assignment, Build Payload data flow, and a non-goals
    section.
  • docs/live-testing-checklist.md — first-run setup, sync pill, Tags,
    Provisioning Builder + Build Payload, EntityPicker, and 1.5 → 1.6
    rollback notes.
  • docs/security-report.md — destructive confirmations always
    enforced, idempotency keys, EntityPicker, snapshot retention.
  • docs/runway-overview.md — removed fabricated test count and bundle
    size claims.
  • CONTRIBUTING.md — added branch/PR expectations and CHANGELOG
    discipline section.
  • .github/pull_request_template.md — added Risks section.
  • .github/ISSUE_TEMPLATE/bug_report.md — added Setup state and
    expanded affected-surface options for Setup, Sync pill, Tags,
    Provisioning Builder, Build Payload.
  • CHANGELOG.md — added [Unreleased] Documentation entry.

Stale docs removed

  • "Confirm destructive actions toggle" (toggle was removed in v1.6;
    destructive confirmations are always enforced).
  • "enter user object ID" / "raw GUID" instructions on Change Primary
    User (replaced by EntityPicker search by display name, UPN, or mail).
  • Settings-side individual tag mapping editing (now lives in the Tags
    side drawer; Settings only handles JSON import/export).
  • Section-numbered references like "Section 9 Tag Mapping" (section
    numbers shift; user guide now indexes by section title).
  • Fabricated "256 / 256 tests passing" and bundle-size benchmarks in
    docs/runway-overview.md.

Validation

  • npm run lint ✅ (no errors)
  • npm run typecheck
  • npm run test ✅ 319 unit + api tests pass (31 files)
  • npm run test:e2e ✅ 30 e2e tests pass (4 files)
  • npm run build ✅ client + server bundles built clean
  • package.json version unchanged (still 1.6.0)
  • Stale-phrase grep (Section 9, Confirm destructive,
    user object ID, raw GUID, never-disable-confirmations) — only
    hits in CHANGELOG entries (describing the removals) and in new docs
    describing that raw GUIDs are no longer required.

Screenshots

No screenshots updated — current docs do not embed UI screenshots and
the repo does not have an automated screenshot tooling convention. If a
screenshot pass is desired for the user guide, recommend doing it as a
follow-up against a frozen build so screenshots stay in sync with
release artifacts.

Risks

  • Pure documentation / template / changelog changes — no runtime,
    schema, or behaviour impact.
  • Linked anchors and relative paths inside docs were preserved or
    updated; reviewers should still spot-check docs/user-guide.md
    navigation links if they spot an anchor renamed.

Remaining decisions

  • Screenshot generation tooling is not in scope for this PR.
  • A future docs sweep can drop docs/runway-overview.md if its content
    is fully covered by README + user guide.

Bring all user-facing docs in line with the v1.6 app shape after the
Tags / Provisioning Builder / Build Payload / first-run setup passes.

- README: add "what Runway intentionally does not do", surface first-run
  setup, sync status pill, Tags view, Build Payload, EntityPicker, and
  single-device destructive actions; replace stale "1.0 Readiness" with
  a tenant testing warning.
- docs/user-guide: end-to-end rewrite with first-run setup, sync pill,
  Tags view + drawer, Provisioning Builder + Build Payload availability
  states, EntityPicker primary-user search, tabbed device detail with
  ?tab= deep-links, tenant testing workflow. Drop "Confirm destructive
  actions toggle", "enter user object ID", and "raw GUID" instructions.
- docs/architecture: document app-only vs delegated split, first-run
  completion criteria, sync status source of truth, raw_graph_assignment
  and tag_config cleanup, Build Payload data flow, and a non-goals list.
- docs/live-testing-checklist: add first-run setup, sync pill, Tags,
  Build Payload, EntityPicker, and 1.5 -> 1.6 rollback notes.
- docs/security-report: clarify destructive confirmations are always
  enforced, idempotency keys, EntityPicker, and snapshot retention.
- docs/runway-overview: drop fabricated test/bundle benchmarks.
- CONTRIBUTING: branch/PR rules and CHANGELOG discipline section.
- .github: PR template gains a Risks section; bug_report adds new
  affected-surface options for Setup, Tags, Provisioning Builder, and
  Build Payload.
Summarise the v1.6 doc/repo polish under [Unreleased] without bumping
the package version.
Trim the wall-of-text up top and add lightweight structure without
pushing into marketing-flashy territory:

- Lead with the one-line tagline above the badges, add a Local-first
  badge alongside the existing CI/MIT/Windows ones.
- Add a compact "At a glance" facts table (platform, data sources,
  residency, auth, egress, targeting, out-of-scope) right after the
  intro.
- Add a small inline "Jump to" link row to the most-used sections.
- Collapse the long .env reference, ConfigMgr signal table, the two
  Graph permission lists, the full npm scripts table, and the project
  layout tree into <details> blocks so the page scans quickly.
- Promote the most-used npm scripts (dev, check, build, tauri:dev,
  tauri:build) into a short top-level table; keep the full list inside
  the collapsible.
- Drop the "v1.0" SCCM phrasing now that the app has shipped past 1.0.
- README .env reference now points to .env.example for the full
  annotated template, drops the engine tunables that moved to Settings
  in 1.5, and adds LOG_LEVEL + a reminder that DB-backed Settings take
  precedence over env overrides.
- runway-overview "take action" line replaces the stale "bulk-act
  across the whole queue" wording with the current single-device
  destructive set + bulk-restricted-to-sync/reboot/rotate-laps reality.
@giftedloser giftedloser marked this pull request as ready for review May 2, 2026 16:47
@giftedloser giftedloser merged commit 013422f into main May 2, 2026
1 check passed
@giftedloser giftedloser deleted the codex/docs-userguide-repo-polish branch May 2, 2026 16:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant