Skip to content

docs(readme): persona-first restructure of the README top (#156) - #171

Merged
takashikasuya merged 1 commit into
mainfrom
claude/readme-persona-restructure
Jul 15, 2026
Merged

docs(readme): persona-first restructure of the README top (#156)#171
takashikasuya merged 1 commit into
mainfrom
claude/readme-persona-restructure

Conversation

@takashikasuya

Copy link
Copy Markdown
Contributor

Addresses #156.

⚠️ Stacks on #170 (#160). This PR's new top block links to docs/concepts.md, which is added
in #170. Merge #170 first, then this one — otherwise the two docs/concepts.md links dangle
until it lands. (Once #170 merges to main, this PR's diff reduces to just the README change.)

Summary

Reworks the first screenful of the 690-line README so a first-time reader immediately sees
what it is → what it looks like → the first command → where to go for their goal, instead of
hitting Breaking-change / Azure-compat / IaC detail up front (the #156 acceptance criterion:
"README冒頭スクロール1画面以内に「何か・見た目・最初の1コマンド」が収まる").

New top section (right after the intro):

  • 📸 Screenshot/GIF placeholder — an HTML-comment slot + a text pointer to the 3 core screens
    (/resources tree → /points/{id} chart → control dialog). Actual captures need a live UI, which
    this automated environment can't run, so they're explicitly left for a maintainer (marked in-file).
  • 🚀 5-minute quickstart — 2 commands + login.
  • 主要機能 — feature bullets.
  • 🧭 目的別の入口 — the persona table the issue asked for (A demo / B MQTT / C gateway-dev /
    D twin / E prod / F API), each linking straight to the relevant doc.

Moved "migration / compat / IaC" detail out of the top (the other acceptance criterion):

  • The Timescale→Parquet Breaking-change block and the Azure IoT Hub block in the architecture
    header are collapsed to one-line pointers. Their full content already lives in the linked docs
    (oss-warm-parquet-lake.md / oss-tier-architecture.md; system-architecture.md already documents
    the Kandt/IoT Hub bridge), so nothing is lost.
  • Removed the duplicated legacy host-run steps (§5/§6/§7 — they repeated §4); folded the one unique
    detail (WithLocalAuth) into a pointer to getting-started.md. Retitled the detailed quickstart to
    「起動手順(詳細)」.
  • Mirrored the persona table + screenshot note in the English summary.

Test plan

  • All docs/ links in the README verified to resolve (the only "missing" hit is the example path
    inside the screenshot HTML comment — inert, not rendered).
  • Markdown code-fences balanced (40, even); the MQTT intra-page anchor target header exists.
  • No information loss: every demoted/removed block's content is preserved in a linked doc or a
    concise pointer.

Checklist

  • I read CONTRIBUTING.md and followed the coding conventions in CLAUDE.md
  • I added or updated tests — n/a (docs-only)
  • I updated relevant docs (this PR is the README)

Out of scope (possible follow-ups): real screenshots/GIF capture; relocating the lower-half env-var /
ports / deploy reference tables into dedicated docs (they already carry doc pointers and sit below the
fold).

🤖 Generated with Claude Code


Generated by Claude Code

@takashikasuya
takashikasuya force-pushed the claude/readme-persona-restructure branch from c7d6a61 to a1c9d86 Compare July 15, 2026 13:03
…156)

Reworks the first screenful of the 690-line README so a first-time reader
immediately sees what it is, what it looks like, and the first command —
instead of hitting Breaking-change / Azure-compat / IaC detail up front.

New top section (after the intro):
- screenshot/GIF placeholder (HTML comment + text pointer to the 3 core screens;
  actual captures need a live UI, so they are left for a maintainer)
- 5-minute quickstart (2 commands + login)
- ✨ 主要機能 (feature bullets)
- 🧭 目的別の入口 — persona table A–F (demo / MQTT / gateway dev / twin / prod /
  API) linking straight to the relevant doc

Demoted migration/compat detail from the architecture header to concise
one-line pointers (Timescale→Parquet breaking change → oss-warm-parquet-lake.md
/ oss-tier-architecture.md; Azure IoT Hub bridge → system-architecture.md, which
already documents it). Removed the duplicated legacy host-run steps (§5/§6/§7,
which repeated §4) and folded the one unique detail (WithLocalAuth) into a
pointer to getting-started.md. Retitled the detailed quickstart to
「起動手順(詳細)」. Mirrored the persona table + screenshot note in the English
summary.

Note: builds on the concepts.md added in #160 (PR #170) — merge that first so the
docs/concepts.md links resolve.

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Signed-off-by: Claude <noreply@anthropic.com>
@takashikasuya
takashikasuya force-pushed the claude/readme-persona-restructure branch from a1c9d86 to ef754be Compare July 15, 2026 13:05
@takashikasuya
takashikasuya merged commit 82c4b17 into main Jul 15, 2026
5 checks passed
@takashikasuya
takashikasuya deleted the claude/readme-persona-restructure branch July 15, 2026 13:06
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.

2 participants