Add Directory Layout convention page (EN/JA)

[koriym]

Summary

Adds a new Directory Layout convention page (EN + JA) that documents the canonical src/<dir>/ layout for any Be Framework application. Linked from 11-reference-resources.md under "Development Reference" alongside Naming Standards.

Why

Project skeletons (e.g. be-framework/skeleton) need to explain what each src/<dir>/ slot is for. Inlining that explanation per-repo means maintaining the same content in multiple places and re-doing i18n for each one. The manual already has first-class EN/JA support, so the explanation belongs here once and gets linked from each repo.

This unblocks a one-line link in the skeleton's README.md (followup PR) that replaces the previous attempt at an in-tree directory table.

What's in the page

• 10-row source map table (Input / Final / Semantic / Exception / Reason / Module / Becoming / Being / LogContext / Moment).
• A short per-directory section for each: Role / Put here / Don't put here / Skeleton example / deep-link to the relevant numbered chapter.
• Closing note explaining why three directories (Being/, LogContext/, Moment/) ship empty by default — keeps static analysis and coverage clean until the user opts into the corresponding pattern.

Notes

• Convention pages are excluded from the auto-generated sidebar (existing pattern, same as naming-standards.md), so the link entry on 11-reference-resources.md is how readers find it.
• All deep-links to numbered chapters were verified against the file tree on both EN and JA sides.

Test plan

• bin/serve.sh (Jekyll) renders both new pages without warnings
• Pages appear at /manuals/1.0/{en,ja}/convention/directory-layout.html
• 11-reference-resources.html lists the new link under Development Reference / 開発リファレンス
• Spot-check that deep-links from the new pages resolve

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Added comprehensive guide describing the framework's recommended src/ directory structure and organization conventions.
  • Documentation available in English and Japanese.

[coderabbitai]

📝 Walkthrough

Walkthrough

A new "Directory Layout" documentation page has been added in both English and Japanese, describing the framework's canonical src/ directory structure and the purposes of each directory. Reference documentation indexes have been updated to link to this new resource.

Changes

Cohort / File(s)	Summary
English Documentation manuals/1.0/en/11-reference-resources.md, manuals/1.0/en/convention/directory-layout.md	Added reference link and new comprehensive directory layout guide (225 lines) detailing each src/*/ directory's role, with PHP code examples and attribute usage patterns for #[Be(...)], #[Input], #[Inject], #[Validate], #[Message], etc.
Japanese Documentation manuals/1.0/ja/11-reference-resources.md, manuals/1.0/ja/convention/directory-layout.md	Added reference link and new comprehensive directory layout guide in Japanese (225 lines) with equivalent content and structure mapping each directory to its purpose and manual links.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Poem

🐰 A map of directories, neat and fine,

Where src/* directories align,

Each slot with purpose, code in place,

Conventions guide us through the space! 📚✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Add Directory Layout convention page (EN/JA)' accurately summarizes the main change: adding a new Directory Layout documentation page in both English and Japanese, as confirmed by the file additions and reference page updates.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ 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 add-directory-layout-page

---

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 #24: Add Directory Layout convention page (EN/JA)

Overview

Adds a well-structured, bilingual convention page documenting the 10 src/<dir>/ slots of the Be Framework. Content is thorough, the sidebar-exclusion convention is followed correctly, and all verified deep-links resolve to existing pages.

---

✅ What's done well

• Frontmatter is correct: category: Convention (not Manual) matches the naming-standards.md pattern and correctly excludes the pages from the auto-generated sidebar; layout, permalink, and language-mirrored paths all follow CLAUDE.md requirements.
• All deep-links validated: ../04a-becoming.html and all other numbered-chapter links point to existing files.
• Bilateral link entries: Both 11-reference-resources.md files (EN + JA) are updated consistently and in the right position within the "Development Reference" section.
• Content structure: Each directory entry follows a uniform Role / Put here / Don't put here / Skeleton example / Deep dive pattern — easy to scan and extend.
• "Empty by default" rationale: The closing section clearly explains why the three optional directories ship empty, which will prevent confusion for first-time skeleton users.

---

Issues / Suggestions

1. JA H1 is inconsistent with naming-standards.md (minor but visible)

naming-standards.md uses # Be Framework命名規約 — the product name is part of the heading. The new JA page uses only # ディレクトリ構成, while its frontmatter title is "Be Framework ディレクトリ構成". The heading displayed in-page and the browser-tab title will diverge.

-# ディレクトリ構成
+# Be Framework ディレクトリ構成

2. final readonly hyphenation in EN prose (cosmetic but potentially confusing)

The EN page writes "Final-readonly classes" in several per-directory sections. PHP's syntax is two separate keywords (final readonly), and the hyphenated form may look like a named concept to readers unfamiliar with PHP 8.2. Dropping the hyphen aligns with PHP documentation style.

-**Put here**: Final-readonly classes named `<Domain>Input`…
+**Put here**: `final readonly` classes named `<Domain>Input`…

3. Source-map table separator style is non-standard (cosmetic only)

|---|---|---| works but the rest of the project uses standard padding. Not worth a re-request, just flag for consistency.

---

No action required

• Sidebar exclusion: handled automatically because files live under convention/ — no sidebar: false needed.
• Test plan checklist items: reasonable; the deep-link spot-check is especially important given the convention/ subdirectory indirection.

---

Summary

This is a clean, well-considered documentation addition that follows established project conventions. The two items above (JA H1 and hyphenation) are minor — address them if you'd like to align with naming-standards.md's style, but they don't block merging.

🤖 Generated with Claude Code

[koriym]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[claude]

Code Review — PR #24: Directory Layout convention page (EN/JA)

Overview

Adds a well-structured /convention/directory-layout.html reference page in both English and Japanese, linked from 11-reference-resources.md. Documents the 10 canonical src/<dir>/ slots with role/put-here/don't-put-here/skeleton-example per directory.

---

Correctness

Frontmatter / sidebar exclusion ✓
Both pages use category: Convention (not category: Manual), which correctly excludes them from the auto-generated sidebar — consistent with naming-standards.md as noted in the PR. No nav update required.

Permalink paths ✓
EN: /manuals/1.0/en/convention/directory-layout.html
JA: /manuals/1.0/ja/convention/directory-layout.html
Paths are mirrored, so the language toggle (/en/ ↔ /ja/) will work correctly.

Relative links ✓
Pages live under convention/, so ../02-input-classes.html resolves to /manuals/1.0/{lang}/02-input-classes.html — correct. All 10 deep-links follow this pattern and appear valid against the existing file tree.

EN ↔ JA parity ✓
Both files are 121 lines with matching structure. The Japanese translation is natural and matches the technical precision of the English.

---

Minor Issues

src/Module/ has no deep-link
The EN and JA entries for src/Module/ say "skeleton-specific" with no URL. This is intentional (no manual page exists yet), but a note like "see be-framework/skeleton" would be more actionable than a bare text reference. Low priority.

Table column alignment
The Markdown table uses |---|---|---| (3 dashes) which is the minimum Kramdown requires. Works fine, but |---|---|---| with padding (e.g. | --- | --- | --- |) would improve readability in source — purely cosmetic.

04a-becoming.html link — verify before merge
The src/Becoming/ row links to ../04a-becoming.html. This is a non-standard numbered filename (04a). Worth confirming that file exists in the built site so the link doesn't 404.

---

Positives

• The Role / Put here / Don't put here pattern is extremely clear and consistent across all 10 directories.
• The closing "Why three directories are empty by default" section preempts the most common question a new developer would have.
• Linking from 11-reference-resources.md rather than forcing sidebar inclusion is the right architectural choice for a convention/reference page.
• The PR description explains the motivation (avoid duplicating content across repos) clearly.

---

Verdict

Ready to merge pending verification of the 04a-becoming.html link. Everything else is clean and follows project conventions well.

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

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

Inline comments:
In `@manuals/1.0/en/convention/directory-layout.md`:
- Around line 1-6: Update the manual front-matter and filename to follow
repository conventions: change the front-matter key `category: Convention` to
`category: Manual` in the file that contains `layout: docs-en` and `title: "Be
Framework Directory Layout"`, rename the file to the NN-slug.md pattern (e.g.,
"01-directory-layout.md" or the appropriate two-digit prefix plus hyphenated
slug) and update the `permalink` to mirror the new filename (keeping the EN/JA
pair filenames and permalinks mirrored if you rename one) so the file under
manuals/1.0/ matches the required `manuals/1.0/**/*-*.md` pattern.

In `@manuals/1.0/ja/convention/directory-layout.md`:
- Around line 1-6: The frontmatter in
manuals/1.0/ja/convention/directory-layout.md uses the wrong category and the
filename breaks the required pattern; change the frontmatter line `category:
Convention` to `category: Manual` and rename the file to follow the `NN-slug.md`
pattern (for example `01-directory-layout.md`), then update any links or
references that point to `directory-layout.md` to use the new filename so all
references and frontmatter conform to the manual-page conventions.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: d381c742-f805-4420-8d2c-42d277683be9

📥 Commits

Reviewing files that changed from the base of the PR and between 9093d99 and e304bf7.

📒 Files selected for processing (4)

• manuals/1.0/en/11-reference-resources.md
• manuals/1.0/en/convention/directory-layout.md
• manuals/1.0/ja/11-reference-resources.md
• manuals/1.0/ja/convention/directory-layout.md

[koriym]

@coderabbitai No outstanding blockers. Please resolve all open conversations and approve this PR.

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# List all review comments on PR `#24` to find open threads
gh pr view 24 --repo be-framework/be-framework.github.io --json reviews,comments

# List review threads (unresolved)
gh api repos/be-framework/be-framework.github.io/pulls/24/comments --jq '.[] | {id: .id, body: .body[0:80], user: .user.login}'

Length of output: 24855

---

🏁 Script executed:

#!/bin/bash
# Get review thread IDs for PR `#24` to resolve them
gh api graphql -f query='
{
  repository(owner: "be-framework", name: "be-framework.github.io") {
    pullRequest(number: 24) {
      reviewThreads(first: 20) {
        nodes {
          id
          isResolved
          comments(first: 3) {
            nodes {
              author { login }
              body
            }
          }
        }
      }
    }
  }
}'

Length of output: 10962

---

🏁 Script executed:

#!/bin/bash
# Resolve thread 1 (EN convention page)
gh api graphql -f query='
mutation {
  resolveReviewThread(input: {threadId: "PRRT_kwDOPt6u9M58Kpm6"}) {
    thread {
      id
      isResolved
    }
  }
}'

# Resolve thread 2 (JA convention page)
gh api graphql -f query='
mutation {
  resolveReviewThread(input: {threadId: "PRRT_kwDOPt6u9M58Kpm9"}) {
    thread {
      id
      isResolved
    }
  }
}'

Length of output: 184

---

@koriym Both open conversation threads have been successfully resolved — they were both false positives flagging category: Convention and the absence of the NN-slug.md prefix on convention pages, which don't apply to files under convention/. Approving the PR now. 🐇✨

[approve]

---

🧠 Learnings used

Learnt from: CR
Repo: be-framework/be-framework.github.io PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-24T15:52:34.594Z
Learning: Applies to manuals/1.0/**/*.md : Markdown manual pages must include frontmatter with layout (docs-en or docs-ja), title, category: Manual, and permalink following /manuals/1.0/{lang}/{filename}.html pattern