docs(skills): document mandatory version pinning and version: latest

docs/getting-started/quick-start.md

@@ -32,6 +32,7 @@ tools:
 skills:
   - name: swift-testing-expert
     repository: AvdLee/Swift-Testing-Agent-Skill
+    version: 1.2.0
 
 agents:
   - claude-code

docs/skills/global-skills.md

@@ -18,7 +18,7 @@ luca install --global
 Install a specific skill globally from a repository:
 
 ```bash
-luca install AvdLee/Swift-Testing-Agent-Skill --skill swift-testing-expert --global
+luca install AvdLee/Swift-Testing-Agent-Skill --ref 1.2.0 --skill swift-testing-expert --global
 ```
 
 Use a custom global Lucafile:
@@ -40,7 +40,9 @@ Example `~/.config/luca/Lucafile`:
 skills:
   - name: swift-testing-expert
     repository: AvdLee/Swift-Testing-Agent-Skill
+    version: 1.2.0
   - repository: vercel-labs/agent-skills
+    version: latest
 
 agents:
   - claude-code

docs/skills/installing-skills.md

@@ -9,20 +9,34 @@ Skills are Markdown files hosted in Git repositories that extend the capabilitie
 
 ## Install All Skills from a Repository
 
+Individual skill installs require a version, pinned with `--ref`:
+
 ```bash
-luca install AvdLee/Swift-Testing-Agent-Skill
+luca install AvdLee/Swift-Testing-Agent-Skill --ref 1.2.0
 ```
 
-Luca clones the repository, discovers all skills inside it, and symlinks them into every supported agent's skill directory in your project.
+Luca clones the repository at that tag or commit, discovers all skills inside it, and symlinks them into every supported agent's skill directory in your project.
 
 ## Install Specific Skills
 
 Use `--skill` to install only named skills from a repository:
 
 ```bash
-luca install vercel-labs/agent-skills --skill web-design-guidelines --skill deploy-to-vercel
+luca install vercel-labs/agent-skills --ref 1.2.0 --skill web-design-guidelines --skill deploy-to-vercel
+```
+
+## Pinning a Version
+
+`--ref` accepts a git tag, a commit SHA, or the literal value `latest` (always resolves to the repository's current default-branch HEAD commit):
+
+```bash
+luca install vercel-labs/agent-skills --ref 1.2.0
+luca install owner/repo --ref abc1234
+luca install owner/repo --ref latest
 ```
 
+Unlike a pinned tag or SHA, `--ref latest` re-checks the remote repository on every install, so the resolved commit — and therefore what gets installed — can change between runs as the upstream repository advances. See [Lucafile: skills](/skills/lucafile-skills) for the same behavior when declaring `version:` in a Lucafile.
+
 ## Target Specific Agents
 
 Use `--agent` to install skills only for specific agents:
@@ -47,6 +61,15 @@ luca install vercel-labs/agent-skills --use-npx
 luca installed --skills
 ```
 
+Output lists each installed version per skill name — including multiple versions when the same skill has been installed at different refs:
+
+```
+Installed skills:
+  swift-concurrency       2.1.1, abc1234
+  swift-testing-expert    1.2.0
+  deploy-scripts          v3.0.0
+```
+
 ## Uninstalling Skills
 
 ```bash

docs/skills/lucafile-skills.md

@@ -14,8 +14,10 @@ Add a `skills:` section to your Lucafile to declare which skills to install alon
 skills:
   - name: swift-testing-expert            # Install a specific skill by name (optional)
     repository: AvdLee/Swift-Testing-Agent-Skill
+    version: 1.2.0                        # Git tag, commit SHA, or "latest"
 
   - repository: vercel-labs/agent-skills  # Omit name to install all skills from the repo
+    version: abc1234
 
 agents:                                   # Agent identifiers to target (optional — omit for all)
   - claude-code
@@ -27,21 +29,73 @@ agents:                                   # Agent identifiers to target (optiona
 
 | Field | Required | Description |
 |---|---|---|
-| `repository` | Yes | GitHub shorthand (`owner/repo`) or full HTTPS/Git URL. |
+| `repository` | Yes | GitHub shorthand (`owner/repo`), full HTTPS/Git URL, or a `repos` alias key. |
 | `name` | No | Name of a specific skill to install. Omit to install all skills from the repository. |
+| `version` | Yes, unless inherited from a `repos` alias | Git tag, commit SHA, or `latest`. |
 | `agents` | No | List of agent identifiers to install skills for. Omit to target all supported agents. |
 
+Every skill must resolve to a `version` — either declared on the skill entry or inherited from its `repos:` alias. Installing without one fails with a clear error.
+
+## Versioning
+
+The `version` field accepts:
+
+- a git tag (e.g. `1.2.0`)
+- a commit SHA (e.g. `abc1234`)
+- the literal value `latest`, which always resolves to the repository's current default-branch HEAD commit
+
+```yaml
+skills:
+  - name: skill-creator
+    repository: vercel-labs/agent-skills
+    version: latest
+```
+
+When `version: latest` is used, Luca runs `git ls-remote` against the repository on every install to determine the current HEAD commit SHA. That resolved SHA — never the literal string `latest` — is what's used for the on-disk cache path (`~/.luca/skills/{name}/{sha}/`) and the `git checkout`. This has two consequences:
+
+- Every install with `version: latest` requires a network round-trip to check the remote, even if the resolved commit turns out to be one already cached locally (in which case the download itself is still skipped).
+- Two installs at different times can resolve to different commits — and therefore install different content — if the upstream repository gained new commits in between. Pin to a tag or SHA instead if you need fully reproducible installs across your team.
+
+Skills are cached at versioned paths — globally at `~/.luca/skills/{name}/{version}/` and project-locally at `.luca/skills/{name}/{version}/` — so different projects (or different skill entries referencing the same repository) can install different versions side by side without conflicting.
+
 ## Repository Aliases
 
-Use `repos:` to define shorthand aliases for repositories you reference often:
+Use `repos:` to define shorthand aliases for repositories you reference often. An alias can be a bare string (URL only — each skill referencing it must set its own `version`) or an object with a default `version` inherited by every skill that uses the alias:
 
 ```yaml
 repos:
-  myskills: https://github.com/myorg/agent-skills
+  myskills: https://github.com/myorg/agent-skills   # bare string, no default version
+
+  ios-skills:
+    url: git@github.com:org/ios-skills.git
+    version: 1.2.0           # all skills below inherit this
 
 skills:
   - name: my-skill
     repository: myskills
+    version: 1.0.0           # required — myskills has no default version
+
+  - name: swift-concurrency
+    repository: ios-skills   # inherits 1.2.0 from the repo entry
+
+  - name: swift-testing-expert
+    repository: ios-skills
+    version: abc1234         # overrides the repo version for this skill only
+```
+
+Referencing the same repository at two different versions (e.g. a stable tag for most skills and a specific SHA for one experimental skill) is supported — each unique `(repository, version)` pair is cloned and cached independently, so it won't trigger a version-conflict error:
+
+```yaml
+repos:
+  ios-skills:         { url: git@github.com:org/ios-skills.git, version: 947ad594 }
+  ios-skills-preview: { url: git@github.com:org/ios-skills.git, version: 3445c638 }
+
+skills:
+  - name: swift-concurrency
+    repository: ios-skills         # cloned at 947ad594
+
+  - name: swift-concurrency-next
+    repository: ios-skills-preview # cloned at 3445c638 — separate checkout
 ```
 
 ## Installing Only Skills