From 110d17d8ca27126793855552ba85272a5b36a526 Mon Sep 17 00:00:00 2001
From: Aly Raffauf <aly@aly.codes>
Date: Sun, 15 Feb 2026 20:50:34 -0500
Subject: [PATCH] show descriptions and groups in command hints

---
 source/app.tsx     | 29 ++++++++++++++++++++++-------
 source/commands.ts | 26 +++++++++++++++++++++++---
 2 files changed, 45 insertions(+), 10 deletions(-)

diff --git a/source/app.tsx b/source/app.tsx
index cf2a401..159e42f 100644
--- a/source/app.tsx
+++ b/source/app.tsx
@@ -25,14 +25,28 @@ const PROJECT_CACHE_TTL = 5 * 60 * 1000;
 let cachedProjects: Map<string, string> | null = null;
 let cachedProjectsAt = 0;
 
+const HINT_PAD = 26;
+
 function CommandHints({input}: {input: string}) {
 	if (input === '?') {
-		return commands.map(c => (
-			<Text key={c.prefix} dimColor>
-				{'  '}
-				{c.hint}
-			</Text>
-		));
+		const elements: React.ReactNode[] = [];
+		let lastGroup = '';
+		for (const c of commands) {
+			if (c.group !== lastGroup && lastGroup) {
+				elements.push(<Text key={`sep-${c.group}`}> </Text>);
+			}
+
+			lastGroup = c.group;
+			elements.push(
+				<Text key={c.prefix} dimColor>
+					{'  '}
+					{c.hint.padEnd(HINT_PAD)}
+					{c.description}
+				</Text>,
+			);
+		}
+
+		return <>{elements}</>;
 	}
 
 	if (input) {
@@ -41,7 +55,8 @@ function CommandHints({input}: {input: string}) {
 			.map(c => (
 				<Text key={c.prefix} dimColor>
 					{'  '}
-					{c.hint}
+					{c.hint.padEnd(HINT_PAD)}
+					{c.description}
 				</Text>
 			));
 	}
diff --git a/source/commands.ts b/source/commands.ts
index 3199432..55769a5 100644
--- a/source/commands.ts
+++ b/source/commands.ts
@@ -16,13 +16,17 @@ export type CommandContext = {
 type Command = {
 	prefix: string;
 	hint: string;
+	description: string;
+	group: 'tasks' | 'nav' | 'app';
 	run: (args: string, ctx: CommandContext) => Promise<void>;
 };
 
 export const commands: Command[] = [
 	{
 		prefix: 'done ',
-		hint: 'done <number>',
+		hint: 'done <n>',
+		description: 'complete a task',
+		group: 'tasks',
 		run: async (args, {api, tasks, setTasks, setMessage}) => {
 			const num = Number.parseInt(args, 10);
 			const task = tasks[num - 1];
@@ -37,7 +41,9 @@ export const commands: Command[] = [
 
 	{
 		prefix: 'edit ',
-		hint: 'edit <n> [due|p1-p4|labels|desc|project|title]',
+		hint: 'edit <n> <field> <value>',
+		description: 'edit a task field',
+		group: 'tasks',
 		run: async (args, {api, tasks, projects, setTasks, setMessage}) => {
 			const spaceIdx = args.indexOf(' ');
 			const numStr = spaceIdx === -1 ? args : args.slice(0, spaceIdx);
@@ -105,7 +111,9 @@ export const commands: Command[] = [
 
 	{
 		prefix: 'desc ',
-		hint: 'desc <number>',
+		hint: 'desc <n>',
+		description: 'show task description',
+		group: 'tasks',
 		run: async (args, {tasks, setMessage}) => {
 			const num = Number.parseInt(args, 10);
 			const task = tasks[num - 1];
@@ -120,6 +128,8 @@ export const commands: Command[] = [
 	{
 		prefix: 'add ',
 		hint: 'add <task>',
+		description: 'add a new task',
+		group: 'tasks',
 		run: async (args, {api, tasks, setTasks}) => {
 			const task = await api.quickAddTask({text: args});
 			setTasks([...tasks, task]);
@@ -128,6 +138,8 @@ export const commands: Command[] = [
 	{
 		prefix: 'filter ',
 		hint: 'filter <query>',
+		description: 'filter tasks',
+		group: 'nav',
 		run: async (args, {setView}) => {
 			setView({type: 'filter', query: args});
 		},
@@ -135,6 +147,8 @@ export const commands: Command[] = [
 	{
 		prefix: 'refresh',
 		hint: 'refresh',
+		description: 'refresh tasks',
+		group: 'nav',
 		run: async (_args, {refresh}) => {
 			await refresh();
 		},
@@ -143,6 +157,8 @@ export const commands: Command[] = [
 	{
 		prefix: 'today',
 		hint: 'today',
+		description: "show today's tasks",
+		group: 'nav',
 		run: async (_args, {setView}) => {
 			setView({type: 'filter', query: 'today'});
 		},
@@ -151,6 +167,8 @@ export const commands: Command[] = [
 	{
 		prefix: 'home',
 		hint: 'home',
+		description: 'go to home view',
+		group: 'nav',
 		run: async (_args, {setView, homeFilter}) => {
 			setView({type: 'filter', query: homeFilter});
 		},
@@ -159,6 +177,8 @@ export const commands: Command[] = [
 	{
 		prefix: 'quit',
 		hint: 'quit',
+		description: 'exit dewy',
+		group: 'app',
 		run: async (_args, {exit}) => {
 			exit();
 		},
-- 
2.51.2