improvements to list and better sync behavior

.changeset/list-project-default.md

@@ -0,0 +1,5 @@
+---
+'skilless': minor
+---
+
+`skilless list` now lists the current project's skills by default, including ones in the project's own skill folders (⌂), marks global skills with ⊕, and drops the date. Pass `--lib` to list your whole library. It now reads only what is on this machine, so it's instant; pass `--sync` to check skilless.dev first.

.changeset/local-first-commands.md

@@ -0,0 +1,5 @@
+---
+'skilless': minor
+---
+
+Commands now work from what is on this machine and send their changes to skilless.dev in a background process, so they finish right away. Pass `--sync` to read the latest from skilless.dev first. The background process also checks for changes made elsewhere and the next command tells you to run `skilless sync`. skilless now tells you when a new version is out.

apps/web/src/content/docs/cli.md

@@ -5,6 +5,10 @@ description: Every skilless command and option.
 
 Run `skilless <command> --help` for the same information in your terminal. Every command also takes `--cwd <path>` to run as if from another directory.
 
+Commands only read what is on this machine, so they finish right away and work offline. Anything they change is sent to skilless cloud in the background. Commands that read your library also take `-s, --sync` to check skilless cloud for changes made elsewhere first. See [sync](/docs/cloud/sync).
+
+skilless tells you when a new version is out. Set `NO_UPDATE_NOTIFIER=1` to turn that off.
+
 ## init
 
 Create your library at `~/.skilless`.
@@ -92,15 +96,17 @@ skilless delete <skills...>
 
 ## list
 
-List the skills in your library.
+List every skill this project's agents get, and how each one reaches them: ⊕ for a global skill, ⌂ for one that sits in the project's own skill folders. Outside a project, it lists your library.
 
 ```bash
 skilless list
 ```
 
-| Option                | Description                                                |
-| --------------------- | ---------------------------------------------------------- |
-| `-p, --project [key]` | List this project's skills, or another project's, instead. |
+| Option                | Description                            |
+| --------------------- | -------------------------------------- |
+| `-l, --lib`           | List every skill in your library.      |
+| `-d, --details`       | Show what each skill does.             |
+| `-p, --project [key]` | List another project's skills instead. |
 
 ## install
 

apps/web/src/content/docs/cloud/sync.md

@@ -27,7 +27,19 @@ skilless sync
 
 Sync runs in both directions. New skills and edits go up from this machine and down from your others, and a skill deleted in one place is deleted everywhere. It then relinks this project's skills and your global ones to match.
 
-Changes you make while offline are queued and sent the next time a command reaches the server.
+## Between syncs
+
+Every other command works from what is on this machine, so it finishes right away. What it changes (a new skill, an edit, a skill added to a project, one made global or deleted) is sent to skilless cloud by a process that runs in the background after the command finishes. If that can't reach the server, the change waits and goes with your next command, and skilless tells you.
+
+The background process also checks every so often for changes made somewhere else, like on another machine or on skilless.dev. When it finds some, your next command says so, and you run `skilless sync` to bring them here. Nothing comes down until you ask for it.
+
+To read the latest from skilless cloud for one command, pass `--sync`:
+
+```bash
+skilless list --sync
+```
+
+Set `SKILLESS_BACKGROUND=0` to turn the background process off. Your changes then wait for `skilless sync`.
 
 ## Conflicts
 

packages/skilless/package.json

@@ -39,6 +39,7 @@
 	},
 	"devDependencies": {
 		"@types/node": "catalog:",
+		"@types/update-notifier": "^6.0.8",
 		"commander": "catalog:",
 		"enquirer": "^2.4.1",
 		"ora": "^9.4.1",
@@ -48,5 +49,8 @@
 		"typescript": "catalog:",
 		"vitest": "catalog:",
 		"zod": "catalog:"
+	},
+	"dependencies": {
+		"update-notifier": "^7.3.1"
 	}
 }

packages/skilless/src/bin.ts

@@ -1,5 +1,13 @@
 #!/usr/bin/env node
 
+import updateNotifier from 'update-notifier';
 import { cli } from '@/cli';
+import { BACKGROUND_COMMAND } from '@/utils/background';
+import { NAME, VERSION } from '@/utils/version';
+
+// checks npm in its own detached process, and says so on a later run
+if (process.argv[2] !== BACKGROUND_COMMAND) {
+	updateNotifier({ pkg: { name: NAME, version: VERSION } }).notify();
+}
 
 cli.parse();

packages/skilless/src/cli.ts

@@ -1,7 +1,14 @@
 import { program } from 'commander';
 import * as commands from '@/commands';
+import { BACKGROUND_COMMAND, showNotices, startBackground } from '@/utils/background';
 import { DESCRIPTION, NAME, VERSION } from '@/utils/version';
 
+/**
+ * Talk to the server themselves, so a background run after them would only
+ * repeat the work — or, for the background command, start itself again.
+ */
+const QUIET = new Set([BACKGROUND_COMMAND, 'sync', 'install', 'auth']);
+
 const cli = program
 	.name(NAME)
 	.description(DESCRIPTION)
@@ -24,6 +31,13 @@ const cli = program
 	.addCommand(commands.sync)
 	// Put the built-in help command back with the regular commands.
 	.commandsGroup('Commands:')
-	.helpCommand(true);
+	.helpCommand(true)
+	.addCommand(commands.background, { hidden: true })
+	.hook('postAction', (_, action) => {
+		if (QUIET.has(action.name())) return;
+
+		showNotices();
+		startBackground(action.opts().cwd ?? process.cwd());
+	});
 
 export { cli };