fix: doctor deletions check and onboard docs improvements

- Fix doctor to treat empty deletions.jsonl as valid (0 entries OK status)
- Fix HydrateDeletionsManifest to create empty file when no deletions found
- Add --parent flag documentation to onboard command
- Add CLI --help tip throughout onboard documentation

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

cmd/bd/doctor.go

@@ -2078,10 +2078,17 @@ func checkDeletionsManifest(path string) doctorCheck {
 
 	deletionsPath := filepath.Join(beadsDir, "deletions.jsonl")
 
-	// Check if deletions.jsonl exists and has content
+	// Check if deletions.jsonl exists
 	info, err := os.Stat(deletionsPath)
-	if err == nil && info.Size() > 0 {
-		// Count entries
+	if err == nil {
+		// File exists - count entries (empty file is valid, means no deletions)
+		if info.Size() == 0 {
+			return doctorCheck{
+				Name:    "Deletions Manifest",
+				Status:  statusOK,
+				Message: "Present (0 entries)",
+			}
+		}
 		file, err := os.Open(deletionsPath) // #nosec G304 - controlled path
 		if err == nil {
 			defer file.Close()

cmd/bd/doctor/fix/deletions.go

@@ -67,7 +67,12 @@ func HydrateDeletionsManifest(path string) error {
 	}
 
 	if len(deletedIDs) == 0 {
-		fmt.Println("  No new deleted issues found in git history")
+		// Create empty deletions manifest to signal hydration is complete
+		// This prevents the check from re-warning after --fix runs
+		if err := deletions.WriteDeletions(deletionsPath, nil); err != nil {
+			return fmt.Errorf("failed to create empty deletions manifest: %w", err)
+		}
+		fmt.Println("  No deleted issues found in git history (created empty manifest)")
 		return nil
 	}
 

cmd/bd/onboard.go

@@ -63,6 +63,7 @@ bd stale --days 30 --json          # Forgotten issues
 
 # Create and manage
 bd create "Title" -t bug|feature|task -p 0-4 --json
+bd create "Subtask" --parent <epic-id> --json  # Hierarchical subtask
 bd update <id> --status in_progress --json
 bd close <id> --reason "Done" --json
 
@@ -128,12 +129,18 @@ Use the beads MCP server for native function calls instead of shell commands:
 - **README.md** - User-facing documentation
 - **docs/CLI_REFERENCE.md** - Complete command reference
 
+## CLI Help
+
+Run ` + "`bd <command> --help`" + ` to see all available flags for any command.
+For example: ` + "`bd create --help`" + ` shows ` + "`--parent`" + `, ` + "`--deps`" + `, ` + "`--assignee`" + `, etc.
+
 ## Important Rules
 
 - ✅ Use bd for ALL task tracking
 - ✅ Always use ` + "`--json`" + ` flag for programmatic use
 - ✅ Run ` + "`bd sync`" + ` at end of sessions
 - ✅ Test with ` + "`BEADS_DB=/tmp/test.db`" + `
+- ✅ Run ` + "`bd <cmd> --help`" + ` to discover available flags
 - ❌ Do NOT create markdown TODO lists
 - ❌ Do NOT create test issues in production DB
 - ❌ Do NOT commit ` + "`.beads/beads.db`" + ` (JSONL only)
@@ -164,6 +171,7 @@ bd ready --json
 ` + "```bash" + `
 bd create "Issue title" -t bug|feature|task -p 0-4 --json
 bd create "Issue title" -p 1 --deps discovered-from:bd-123 --json
+bd create "Subtask" --parent <epic-id> --json  # Hierarchical subtask (gets ID like epic-id.1)
 ` + "```" + `
 
 **Claim and update:**
@@ -263,6 +271,11 @@ history/
 - ✅ Preserves planning history for archeological research
 - ✅ Reduces noise when browsing the project
 
+### CLI Help
+
+Run ` + "`bd <command> --help`" + ` to see all available flags for any command.
+For example: ` + "`bd create --help`" + ` shows ` + "`--parent`" + `, ` + "`--deps`" + `, ` + "`--assignee`" + `, etc.
+
 ### Important Rules
 
 - ✅ Use bd for ALL task tracking
@@ -270,6 +283,7 @@ history/
 - ✅ Link discovered work with ` + "`discovered-from`" + ` dependencies
 - ✅ Check ` + "`bd ready`" + ` before asking "what should I work on?"
 - ✅ Store AI planning docs in ` + "`history/`" + ` directory
+- ✅ Run ` + "`bd <cmd> --help`" + ` to discover available flags
 - ❌ Do NOT create markdown TODO lists
 - ❌ Do NOT use external issue trackers
 - ❌ Do NOT duplicate tracking systems