docs: Document deprecation timeline and add removal warnings (bd-pndo)

- Add Deprecated section to CHANGELOG.md listing all deprecated commands
- Set removal target: v1.0.0 for all deprecated commands
- Add '(will be removed in v1.0.0)' to all deprecation messages
- Add proper Deprecated field to admin_aliases.go (cleanup, compact, reset)
- Remove manual warning prints from admin aliases (Cobra handles it)

Deprecated commands documented:
- bd relate/unrelate → bd dep relate/unrelate
- bd daemons → bd daemon <subcommand>
- bd cleanup/compact/reset → bd admin <command>
- bd comment → bd comments add
- bd template* → bd mol/formula commands
- bd detect-pollution → bd doctor --check=pollution
- bd migrate-* → bd migrate <subcommand>

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

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

CHANGELOG.md

@@ -52,6 +52,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Update jsonl_file_hash on import operations
   - Prevents spurious hash mismatch warnings
 
+### Deprecated
+
+The following commands are deprecated and will be removed in v1.0.0:
+
+- **`bd relate`** → use `bd dep relate` instead
+- **`bd unrelate`** → use `bd dep unrelate` instead
+- **`bd daemons`** → use `bd daemon <subcommand>` instead
+- **`bd cleanup`** → use `bd admin cleanup` instead
+- **`bd compact`** → use `bd admin compact` instead
+- **`bd reset`** → use `bd admin reset` instead
+- **`bd comment`** → use `bd comments add` instead
+- **`bd template`** → use `bd mol` instead
+- **`bd templates`** → use `bd formula list` instead
+- **`bd template show`** → use `bd mol show` instead
+- **`bd template bond`** → use `bd mol bond` instead
+- **`bd detect-pollution`** → use `bd doctor --check=pollution` instead
+- **`bd migrate-hash-ids`** → use `bd migrate hash-ids` instead
+- **`bd migrate-tombstones`** → use `bd migrate tombstones` instead
+- **`bd migrate-sync`** → use `bd migrate sync` instead
+- **`bd migrate-issues`** → use `bd migrate issues` instead
+
+All deprecated commands continue to work but print a warning. Update your scripts
+and muscle memory before v1.0.0 to avoid breakage.
+
 ### Changed
 
 - **Community tools documentation** (GH#772, GH#776)

cmd/bd/admin_aliases.go

@@ -1,11 +1,7 @@
 package main
 
 import (
-	"fmt"
-	"os"
-
 	"github.com/spf13/cobra"
-	"github.com/steveyegge/beads/internal/ui"
 )
 
 // Hidden aliases for backwards compatibility.
@@ -13,34 +9,34 @@ import (
 // They are hidden from help output but still work for scripts/muscle memory.
 
 var cleanupAliasCmd = &cobra.Command{
-	Use:    "cleanup",
-	Hidden: true,
-	Short:  "Alias for 'bd admin cleanup' (deprecated)",
-	Long:   cleanupCmd.Long,
+	Use:        "cleanup",
+	Hidden:     true,
+	Deprecated: "use 'bd admin cleanup' instead (will be removed in v1.0.0)",
+	Short:      "Alias for 'bd admin cleanup' (deprecated)",
+	Long:       cleanupCmd.Long,
 	Run: func(cmd *cobra.Command, args []string) {
-		fmt.Fprintln(os.Stderr, ui.RenderMuted("Note: 'bd cleanup' is now 'bd admin cleanup'"))
 		cleanupCmd.Run(cmd, args)
 	},
 }
 
 var compactAliasCmd = &cobra.Command{
-	Use:    "compact",
-	Hidden: true,
-	Short:  "Alias for 'bd admin compact' (deprecated)",
-	Long:   compactCmd.Long,
+	Use:        "compact",
+	Hidden:     true,
+	Deprecated: "use 'bd admin compact' instead (will be removed in v1.0.0)",
+	Short:      "Alias for 'bd admin compact' (deprecated)",
+	Long:       compactCmd.Long,
 	Run: func(cmd *cobra.Command, args []string) {
-		fmt.Fprintln(os.Stderr, ui.RenderMuted("Note: 'bd compact' is now 'bd admin compact'"))
 		compactCmd.Run(cmd, args)
 	},
 }
 
 var resetAliasCmd = &cobra.Command{
-	Use:    "reset",
-	Hidden: true,
-	Short:  "Alias for 'bd admin reset' (deprecated)",
-	Long:   resetCmd.Long,
+	Use:        "reset",
+	Hidden:     true,
+	Deprecated: "use 'bd admin reset' instead (will be removed in v1.0.0)",
+	Short:      "Alias for 'bd admin reset' (deprecated)",
+	Long:       resetCmd.Long,
 	Run: func(cmd *cobra.Command, args []string) {
-		fmt.Fprintln(os.Stderr, ui.RenderMuted("Note: 'bd reset' is now 'bd admin reset'"))
 		resetCmd.Run(cmd, args)
 	},
 }

cmd/bd/comments.go

@@ -211,7 +211,7 @@ var commentCmd = &cobra.Command{
 	Args:       cobra.MinimumNArgs(1),
 	Run:        commentsAddCmd.Run,
 	Hidden:     true,
-	Deprecated: "use 'bd comments add' instead",
+	Deprecated: "use 'bd comments add' instead (will be removed in v1.0.0)",
 }
 
 func init() {

cmd/bd/daemons.go

@@ -615,7 +615,7 @@ func init() {
 	// Also add to daemonsCmd for backwards compatibility
 	// Make daemonsCmd a hidden alias that shows deprecation
 	daemonsCmd.Hidden = true
-	daemonsCmd.Deprecated = "use 'bd daemon <subcommand>' instead (e.g., 'bd daemon list')"
+	daemonsCmd.Deprecated = "use 'bd daemon <subcommand>' instead (will be removed in v1.0.0)"
 	daemonsCmd.AddCommand(daemonsListCmd)
 	daemonsCmd.AddCommand(daemonsHealthCmd)
 	daemonsCmd.AddCommand(daemonsStopCmd)

cmd/bd/detect_pollution.go

@@ -21,7 +21,7 @@ var detectPollutionCmd = &cobra.Command{
 	Use:        "detect-pollution",
 	GroupID:    "maint",
 	Hidden:     true, // deprecated, use 'bd doctor --check=pollution' instead
-	Deprecated: "use 'bd doctor --check=pollution' instead",
+	Deprecated: "use 'bd doctor --check=pollution' instead (will be removed in v1.0.0)",
 	Short:      "Detect and optionally clean test issues from database",
 	Long: `Detect test issues that leaked into production database using pattern matching.
 

cmd/bd/migrate_hash_ids.go

@@ -430,6 +430,6 @@ func init() {
 	migrateHashIDsAliasCmd := *migrateHashIDsCmd
 	migrateHashIDsAliasCmd.Use = "migrate-hash-ids"
 	migrateHashIDsAliasCmd.Hidden = true
-	migrateHashIDsAliasCmd.Deprecated = "use 'bd migrate hash-ids' instead"
+	migrateHashIDsAliasCmd.Deprecated = "use 'bd migrate hash-ids' instead (will be removed in v1.0.0)"
 	rootCmd.AddCommand(&migrateHashIDsAliasCmd)
 }

cmd/bd/migrate_issues.go

@@ -714,6 +714,6 @@ func init() {
 	migrateIssuesAliasCmd := *migrateIssuesCmd
 	migrateIssuesAliasCmd.Use = "migrate-issues"
 	migrateIssuesAliasCmd.Hidden = true
-	migrateIssuesAliasCmd.Deprecated = "use 'bd migrate issues' instead"
+	migrateIssuesAliasCmd.Deprecated = "use 'bd migrate issues' instead (will be removed in v1.0.0)"
 	rootCmd.AddCommand(&migrateIssuesAliasCmd)
 }

cmd/bd/migrate_sync.go

@@ -65,7 +65,7 @@ func init() {
 	migrateSyncAliasCmd := *migrateSyncCmd
 	migrateSyncAliasCmd.Use = "migrate-sync"
 	migrateSyncAliasCmd.Hidden = true
-	migrateSyncAliasCmd.Deprecated = "use 'bd migrate sync' instead"
+	migrateSyncAliasCmd.Deprecated = "use 'bd migrate sync' instead (will be removed in v1.0.0)"
 	rootCmd.AddCommand(&migrateSyncAliasCmd)
 }
 

cmd/bd/migrate_tombstones.go

@@ -349,6 +349,6 @@ func init() {
 	migrateTombstonesAliasCmd := *migrateTombstonesCmd
 	migrateTombstonesAliasCmd.Use = "migrate-tombstones"
 	migrateTombstonesAliasCmd.Hidden = true
-	migrateTombstonesAliasCmd.Deprecated = "use 'bd migrate tombstones' instead"
+	migrateTombstonesAliasCmd.Deprecated = "use 'bd migrate tombstones' instead (will be removed in v1.0.0)"
 	rootCmd.AddCommand(&migrateTombstonesAliasCmd)
 }

cmd/bd/relate.go

@@ -48,12 +48,12 @@ func init() {
 	// Backwards compatibility aliases at root level (hidden)
 	relateAliasCmd := *relateCmd
 	relateAliasCmd.Hidden = true
-	relateAliasCmd.Deprecated = "use 'bd dep relate' instead"
+	relateAliasCmd.Deprecated = "use 'bd dep relate' instead (will be removed in v1.0.0)"
 	rootCmd.AddCommand(&relateAliasCmd)
 
 	unrelateAliasCmd := *unrelateCmd
 	unrelateAliasCmd.Hidden = true
-	unrelateAliasCmd.Deprecated = "use 'bd dep unrelate' instead"
+	unrelateAliasCmd.Deprecated = "use 'bd dep unrelate' instead (will be removed in v1.0.0)"
 	rootCmd.AddCommand(&unrelateAliasCmd)
 }
 

cmd/bd/template.go

@@ -61,7 +61,7 @@ var templateCmd = &cobra.Command{
 	Use:        "template",
 	GroupID:    "setup",
 	Short:      "Manage issue templates",
-	Deprecated: "use 'bd mol' instead (formula list, mol show, mol bond)",
+	Deprecated: "use 'bd mol' instead (will be removed in v1.0.0)",
 	Long: `Manage Beads templates for creating issue hierarchies.
 
 Templates are epics with the "template" label. They can have child issues
@@ -79,7 +79,7 @@ To use a template:
 var templateListCmd = &cobra.Command{
 	Use:        "list",
 	Short:      "List available templates",
-	Deprecated: "use 'bd formula list' instead",
+	Deprecated: "use 'bd formula list' instead (will be removed in v1.0.0)",
 	Run: func(cmd *cobra.Command, args []string) {
 		ctx := rootCtx
 		var beadsTemplates []*types.Issue
@@ -144,7 +144,7 @@ var templateListCmd = &cobra.Command{
 var templateShowCmd = &cobra.Command{
 	Use:        "show <template-id>",
 	Short:      "Show template details",
-	Deprecated: "use 'bd mol show' instead",
+	Deprecated: "use 'bd mol show' instead (will be removed in v1.0.0)",
 	Args:       cobra.ExactArgs(1),
 	Run: func(cmd *cobra.Command, args []string) {
 		ctx := rootCtx
@@ -223,7 +223,7 @@ func showBeadsTemplate(subgraph *TemplateSubgraph) {
 var templateInstantiateCmd = &cobra.Command{
 	Use:        "instantiate <template-id>",
 	Short:      "Create issues from a Beads template",
-	Deprecated: "use 'bd mol bond' instead",
+	Deprecated: "use 'bd mol bond' instead (will be removed in v1.0.0)",
 	Long: `Instantiate a Beads template by cloning its subgraph and substituting variables.
 
 Variables are specified with --var key=value flags. The template's {{key}}