Align the tutorial with the app skeleton flow

[koriym]

Summary

• make the tutorial use the Be\App namespace expected by the current skeleton direction
• rename the example input class to PatientArrivalInput so it matches bin/be.php path-to-class resolution
• replace the pseudo bin/be.php rewrite step with the actual URI-style invocation that was verified locally

Verification

• practiced the tutorial flow in a temporary app copied from be-skeleton
• verified php bin/be.php 'patientArrival?bodyTemperature=39.5&heartRate=90'
• verified php bin/be.php 'patientArrival?bodyTemperature=37.0&heartRate=80'
• verified the lethal-vital error case

Summary by CodeRabbit

• Documentation
  • Updated tutorial examples to use CLI invocation with URI-style paths instead of direct code execution.
  • Renamed input object for improved naming clarity.
  • Changed code examples and expected outputs to show JSON and text formats.
  • Updated tutorial content across multiple language versions.

[coderabbitai]

📝 Walkthrough

Walkthrough

The tutorial documentation is updated to rename the input domain object from PatientArrival to PatientArrivalInput and shift Step 8 execution examples from direct PHP instantiation code to CLI invocation via bin/be.php with query parameters, including updated output formats.

Changes

Cohort / File(s)	Summary
Tutorial Documentation manuals/1.0/en/tutorial.md, manuals/1.0/ja/tutorial.md	Renamed input domain from PatientArrival to PatientArrivalInput throughout. Updated Step 8 execution examples from direct PHP code (DI wiring, instantiation, method invocation) to CLI invocation of bin/be.php with URI-style paths and query parameters. Updated corresponding output examples to JSON format for the healthy case and plaintext for error cases.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Possibly related PRs

• feat: add Practice section (P1 Quick Start, P2 Tutorial) #13: Implements the actual code-side renaming of PatientArrival to PatientArrivalInput class and file path that these documentation updates reflect.

Poem

🐰 A patient arrives with a new, clearer name,
Our tutorial dances with the CLI flame,
JSON whispers where PHP once spoke,
Step Eight takes flight with each CLI poke,
The docs now bloom in two languages bright! 🌸

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Align the tutorial with the app skeleton flow' directly relates to the main change: updating tutorial documentation to match the current app skeleton's namespace structure and invocation patterns.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch app-namespace-docs

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[claude]

Code Review — PR #26: Align the tutorial with the app skeleton flow

Overview

This PR updates both the English and Japanese tutorial pages to:

1. Rename PatientArrival → PatientArrivalInput to match the skeleton's path-to-class convention
2. Replace the manual Becoming/Injector bootstrap code in Step 8 with the CLI-based bin/be.php invocation
3. Replace the PHP try/catch error example with the equivalent CLI command + plain-text output
4. Tie the tutorial to the Getting Started guide via an introductory link

The scope is documentation-only (no PHP source changes). Both language versions are updated in sync.

---

What Works Well

• Consistency: Every occurrence of PatientArrival is updated across both EN and JA docs — flow diagrams, file-structure trees, the comparison table, and all code blocks.
• Mirrored EN/JA structure: The two files stay in lockstep, which is required by the permalink-switching mechanism described in CLAUDE.md.
• Simpler Step 8: Replacing six lines of bootstrap PHP with one bash invocation is a genuine improvement. Readers get something they can copy-paste immediately.
• Getting Started link: Adding the prerequisite context upfront sets correct expectations.

---

Suggestions / Issues

1. "being": {} in the JSON output is unexplained

{
  "priority": "IMMEDIATE",
  "color": "RED",
  "bodyTemperature": 39.5,
  "heartRate": 90,
  "being": {}         // ← What is this?
}

A first-time reader will wonder what being represents and why it is empty. A one-sentence note would help, e.g.:

being reflects the intermediate TriageAssessment stage; it is omitted from the final output because EmergencyCase is the resolved type.

---

2. The URI-to-class mapping convention deserves more explanation

The prose says:

bin/be.php maps the URI path patientArrival to Be\App\Input\PatientArrivalInput

This camelCase-path → PascalCase+Input-class rule is the key thing a reader needs to name their own input classes. If Getting Started already explains this convention, consider adding "as described in Getting Started" to avoid duplication. If it doesn't, a brief parenthetical here would prevent confusion.

---

3. Verify the ./getting-started.html link target exists

The new introductory sentence links to ./getting-started.html. If that page doesn't exist yet (or has a different permalink), readers will hit a 404. Worth a quick check before merge.

---

4. Error output format for the lethal-vitals case

The JA error output バイタルサインが生存不可能な状態を示しています。 matches what the old PHP handler showed — good. The EN plain-text output Vital signs indicate non-survivable conditions. is equally clear. Both are fine as-is.

---

5. Minor: "Comparison" section PHP snippet still references $becoming

$patient = new PatientArrivalInput($temp, $hr);
$final = $becoming($patient);

This is intentional (it's a conceptual comparison, not a runnable example), but it might confuse readers who just learned to use bin/be.php. A brief comment like // programmatic API, equivalent to the CLI above would make the intent clear.

---

Summary

Area	Assessment
Correctness	✅ Rename is complete and consistent
Conventions (CLAUDE.md)	✅ Permalinks mirrored, frontmatter untouched
EN/JA parity	✅ Both files updated in sync
Clarity	⚠️ being: {} and URI mapping need a sentence of explanation
Links	⚠️ Verify getting-started.html exists
Security / Performance	N/A (docs only)

Overall this is a clean, well-scoped documentation fix. The two items above (explain being: {}, verify the link) are the only things worth addressing before merge.

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

manuals/1.0/ja/tutorial.md (1)

26-32: ⚠️ Potential issue | 🟡 Minor

Add language identifiers to fenced diagram blocks (markdownlint MD040).

Both changed diagram fences are missing a language tag, which will keep lint warnings active.

Suggested fix

-```
+```text
 PatientArrivalInput（生のバイタルサイン）
     ↓ JTAS プロトコルが評価
 TriageAssessment（蛹の段階）
     ↓ 運命が決定される
 EmergencyCase または ObservationCase（最終的な存在）

@@
- +text
PatientArrivalInput(39.5°C, 90 bpm)
↓ #[Be([TriageAssessment::class])]
TriageAssessment
├─ JTASProtocol->assess() が 'emergency' を返す
└─ $being = Emergency
↓ #[Be([EmergencyCase::class, ObservationCase::class])]
EmergencyCase（$being が Emergency なので）
→ priority: IMMEDIATE
→ color: RED
→ assignER(): "直ちに救急室1を確保..."

Also applies to: 290-302

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@manuals/1.0/ja/tutorial.md` around lines 26 - 32, The fenced diagram blocks
containing the flow with PatientArrivalInput, TriageAssessment, EmergencyCase
and ObservationCase are missing a language identifier and trigger markdownlint
MD040; update each triple-backtick fence that surrounds those ASCII/diagram
blocks to include a language tag (use "text") so the opening fences read ```text
for both occurrences (the block with
PatientArrivalInput／TriageAssessment／EmergencyCase and the block with
PatientArrivalInput(39.5°C, 90 bpm) / JTASProtocol->assess() / EmergencyCase),
leaving the diagram contents unchanged.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Outside diff comments:
In `@manuals/1.0/ja/tutorial.md`:
- Around line 26-32: The fenced diagram blocks containing the flow with
PatientArrivalInput, TriageAssessment, EmergencyCase and ObservationCase are
missing a language identifier and trigger markdownlint MD040; update each
triple-backtick fence that surrounds those ASCII/diagram blocks to include a
language tag (use "text") so the opening fences read ```text for both
occurrences (the block with PatientArrivalInput／TriageAssessment／EmergencyCase
and the block with PatientArrivalInput(39.5°C, 90 bpm) / JTASProtocol->assess()
/ EmergencyCase), leaving the diagram contents unchanged.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: b933f1a5-144e-40e8-8591-b2b6dd942aab

📥 Commits

Reviewing files that changed from the base of the PR and between 05d0930 and af67062.

📒 Files selected for processing (2)

• manuals/1.0/en/tutorial.md
• manuals/1.0/ja/tutorial.md

[claude]

Code Review: PR #26 — Align the tutorial with the app skeleton flow

Overview

This PR updates the tutorial in both EN and JA to:

• Rename PatientArrival → PatientArrivalInput throughout
• Replace the Step 8 manual PHP bootstrap with a bin/be.php CLI invocation
• Add a prerequisite link to "Getting Started"
• Show real CLI output (JSON + plain-text error) instead of inline echo comments

Changes are consistently mirrored across both language versions.

---

Code Quality — Good

• Naming is clearer. PatientArrivalInput explicitly signals this is an Input-layer object, which aligns better with the framework's naming conventions and helps readers understand its role.
• CLI approach is better for a tutorial. Showing php bin/be.php 'patientArrival?...' removes the DI bootstrap boilerplate (5 lines of framework internals) from a tutorial that is supposed to focus on the ontological model. Lower cognitive load for new users.
• Prerequisite link ("picks up from Getting Started") sets appropriate expectations for readers.
• Parity between EN and JA is maintained throughout — all renamed identifiers, code blocks, and prose are updated consistently. Good discipline.

---

Suggestions / Questions

1. "being": {} in the JSON output example:

   {
     "priority": "IMMEDIATE",
     "color": "RED",
     "bodyTemperature": 39.5,
     "heartRate": 90,
     "being": {}
   }

   "being": {} is unexplained. A reader seeing this for the first time will wonder what it means and why it is empty. Even a single sentence — "The being field holds intermediate state and is empty once metamorphosis is complete" — would prevent confusion.

2. Path-to-class resolution is not explained:
   The prose says bin/be.php maps patientArrival to Be\App\Input\PatientArrivalInput, but does not explain the convention (lowercase camelCase path segment → Input namespace + Input suffix). If this convention is documented in Getting Started, a cross-reference would suffice. If not, a brief note here would help readers adapt the pattern to their own inputs.

3. "Comparison with Traditional OOP" section still uses $becoming API:

   $patient = new PatientArrivalInput($temp, $hr);
   $final = $becoming($patient);

   The class rename is correct. The use of $becoming here is intentional (it is a comparison section, not a tutorial step), but a reader who just followed the CLI-based Step 8 may be confused about where $becoming came from. A short comment like // API usage — see Getting Started for setup would clarify this is illustrative, not a step to follow.

4. Error output format: The error case now shows:

   Vital signs indicate non-survivable conditions.

   This is cleaner than the exception block it replaces. Just confirm this is what bin/be.php actually prints to stdout (not stderr) — if it exits non-zero and writes to stderr, the reader's terminal will show it differently and the "Output:" label could mislead.

---

Security / Performance

No concerns — this is a documentation-only change.

---

Verdict

Solid improvement. The suggestions above are minor polish items; none are blockers. The PR is ready to merge as-is, though addressing the "being": {} explanation would noticeably improve the tutorial clarity.