feat(refresh-skills): default to user-level install, add --project scope (#23)

* feat(refresh-skills): default to user-level install, add --project scope

`praxis refresh-skills` installed skills into the user-level home dirs
(~/.claude/skills, ...), which apply globally across every repo. That
over-applied org skills — e.g. praxis-k8s-operations + its MCPs nudging
Claude away from a user's local kubectl in repos that don't want them.

Keep user-level as the default (the main customer case) and add an
opt-in `--project` flag that scopes the install to the current repo
(<cwd>/.claude/skills, etc.) instead of the global home dir.

- harness.Harness.ProjectScoped(dir): rebases SkillDir/AgentDir from
  the home dir onto a project dir, per-host (handles Codex's split
  ~/.agents/skills vs ~/.codex/agents). Non-home paths pass through.
- runPostAuthSetup gains a projectScoped arg; refresh-skills wires it
  to --project and reports scope in text + JSON output.
- Project scope SKIPS the receipt-based "wipe previous profile" steps
  (skills + agents) so a repo-local refresh can't delete the user's
  global install. The disk-scoped orphan sweep still runs (it only
  touches the project-scoped host dirs).

TDD: harness unit tests + runPostAuthSetup project-scope tests (writes
into project dir; does not wipe a pre-seeded user-level install) +
refresh-skills --project RunE test. Full -race suite green.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(refresh-skills): fall back to user scope correctly when getwd fails

Addresses CodeRabbit review on #23. When `refresh-skills --project` is
requested but the working directory can't be resolved, the install fell
back to a user-level target but kept treating it as project-scoped — so
the receipt-based user-level wipes were skipped and the reported scope
lied about where files landed.

- Track an `effectiveProjectScoped` in runPostAuthSetup that drops to
  false on getwd() failure; gate the three user-level wipe steps on it
  and surface it via postAuthState.projectScoped.
- refresh-skills now reports the effective scope (state.projectScoped),
  not the requested flag, in both JSON and text output.
- Regression tests: getwd-failure fallback runs the user-level wipe
  (login_setup_test) and reports user scope (skill_test).

Nitpicks also addressed:
- login_reuse_test stub now asserts login passes projectScoped=false.
- TestProjectScoped_* consolidated into one table-driven test.
- TestRefreshSkills_ProjectFlag_* drive --project/--json through Cobra
  flags to exercise flag wiring.
- README: stop claiming refresh-skills doesn't exist.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: anshulsao

README.md

@@ -105,9 +105,11 @@ praxis login --url https://praxis.your-org.example
 Once saved, you don't need to pass `--url` again. Re-running
 `praxis login` reuses the URL stored in your credentials file.
 
-Re-running `praxis login` is also how you **refresh** your skills and
-the MCP manifest. There's no separate `init`, `install-skill`, or
-`refresh-skills` command — login is the one mutator.
+Re-running `praxis login` is the canonical way to **refresh** your
+skills and the MCP manifest. If you're already logged in and just want
+the refresh without re-authenticating, `praxis refresh-skills` does the
+same thing minus the browser flow (pass `--project` to scope the install
+to the current repo instead of your user-level home dir).
 
 That's it. Open Claude Code (or Codex, or Gemini CLI) and try:
 
@@ -153,12 +155,16 @@ praxis agents [--json]
    agents from /ai-api/custom-agents, prefixed `praxis-`). Read-only,
    no network call.
 
-praxis refresh-skills [--json]
+praxis refresh-skills [--project] [--json]
    Re-fetch this profile's catalog and rewrite skill files + MCP
    snapshot, without re-authenticating. Use when the org has
    published new skills or after `brew upgrade praxis`. Equivalent
    to `praxis login` minus the browser flow; requires existing
    valid credentials.
+   Installs at USER level by default (~/.claude/skills, ...), so
+   skills apply across every repo. Pass --project to scope the
+   install to the current repo (<cwd>/.claude/skills, ...) instead —
+   handy when you want Praxis skills active in one repository only.
 
 praxis update [--yes] [--json]
    Self-update binary. --json implies --yes.

cmd/login.go

@@ -366,7 +366,7 @@ func persistAndSetup(out io.Writer, asJSON bool, profileName, baseURL, token, em
 
 	// Post-auth: install meta-skill, wipe previous org skills, install
 	// this profile's catalog, refresh the MCP tools snapshot.
-	state := postAuthSetup(out, asJSON, baseURL, token)
+	state := postAuthSetup(out, asJSON, baseURL, token, false)
 
 	if asJSON {
 		return render.JSON(out, map[string]any{

cmd/login_reuse_test.go

@@ -41,7 +41,13 @@ func stubPostAuth(t *testing.T) *bool {
 	t.Helper()
 	called := false
 	orig := postAuthSetup
-	postAuthSetup = func(out io.Writer, asJSON bool, baseURL, token string) postAuthState {
+	postAuthSetup = func(out io.Writer, asJSON bool, baseURL, token string, projectScoped bool) postAuthState {
+		// The login path is never project-scoped — only `refresh-skills
+		// --project` is. Guard the compatibility contract so a future
+		// signature change can't silently start passing true here.
+		if projectScoped {
+			t.Errorf("login should call postAuthSetup with projectScoped=false, got true")
+		}
 		called = true
 		return postAuthState{}
 	}

cmd/login_setup.go

@@ -3,6 +3,7 @@ package cmd
 import (
 	"fmt"
 	"io"
+	"os"
 
 	"github.com/Facets-cloud/praxis-cli/internal/agentinstall"
 	"github.com/Facets-cloud/praxis-cli/internal/harness"
@@ -11,6 +12,10 @@ import (
 	"github.com/Facets-cloud/praxis-cli/internal/skillinstall"
 )
 
+// getwd is a seam for the current working directory so project-scoped
+// installs can be tested without chdir'ing the test process.
+var getwd = os.Getwd
+
 // postAuthState captures what runPostAuthSetup did, for inclusion in
 // the JSON output of `praxis login --json`. AI hosts read this to know
 // exactly what changed on disk so they can decide whether to re-read
@@ -23,6 +28,11 @@ type postAuthState struct {
 	removedAgents   []agentInstallationLite
 	snapshotPath    string
 	snapshotWarning string
+	// projectScoped is the *effective* install scope after resolving the
+	// working directory — not the requested flag. It's false when
+	// --project was requested but getwd() failed and the install fell
+	// back to user-level, so callers report where files actually landed.
+	projectScoped bool
 }
 
 // agentInstallationLite is the JSON shape used in login output. Mirrors
@@ -54,9 +64,44 @@ type agentInstallationLite struct {
 // Each step is best-effort: a failure logs a warning to `out` but does
 // not roll back the credentials save. The user can re-run login any
 // time to retry the steps that failed (login is idempotent).
-func runPostAuthSetup(out io.Writer, asJSON bool, baseURL, token string) postAuthState {
+// runPostAuthSetup installs the meta-skill + org catalog + agents into
+// the detected hosts and refreshes the MCP snapshot. When projectScoped
+// is true the install targets are rebased from the user-level home dirs
+// (~/.claude/skills, ...) onto the current working directory
+// (<repo>/.claude/skills, ...), so `praxis refresh-skills --project`
+// scopes skills to a single repo instead of applying them globally.
+//
+// Project scope also SKIPS the receipt-based "wipe previous profile"
+// step (UninstallByPrefix), which operates off the shared user-level
+// receipt and would otherwise delete the user's global install while
+// doing a repo-local refresh. The disk-scoped orphan sweep still runs —
+// it only touches the (project-scoped) host dirs, so it stays safe.
+func runPostAuthSetup(out io.Writer, asJSON bool, baseURL, token string, projectScoped bool) postAuthState {
 	state := postAuthState{}
 	hosts := detectHarnesses()
+	// effectiveProjectScoped tracks the scope we actually install at. It
+	// starts from the requested flag but drops to false if getwd() fails,
+	// because we then fall back to a genuine user-level install — which
+	// must run the user-level wipes and be reported as user scope.
+	effectiveProjectScoped := projectScoped
+	if projectScoped && len(hosts) > 0 {
+		dir, err := getwd()
+		if err != nil {
+			effectiveProjectScoped = false
+			if !asJSON {
+				fmt.Fprintf(out, "Warning: cannot resolve working directory for project-scoped install: %v\n", err)
+				fmt.Fprintln(out, "Falling back to user-level install.")
+			}
+		} else {
+			for i := range hosts {
+				hosts[i] = hosts[i].ProjectScoped(dir)
+			}
+			if !asJSON {
+				fmt.Fprintf(out, "Installing project-scoped under %s\n", dir)
+			}
+		}
+	}
+	state.projectScoped = effectiveProjectScoped
 	noHosts := len(hosts) == 0
 	if noHosts && !asJSON {
 		fmt.Fprintln(out, "No supported AI hosts detected on this machine.")
@@ -103,17 +148,23 @@ func runPostAuthSetup(out io.Writer, asJSON bool, baseURL, token string) postAut
 			}
 		case len(skills) == 0:
 			// Empty catalog is a definitive answer — wipe stale entries.
-			removed := wipePrevProfileSkills(out, asJSON)
-			state.removedSkills = liteResults(removed)
+			// The receipt-based wipe is user-level only (see func doc).
+			if !effectiveProjectScoped {
+				removed := wipePrevProfileSkills(out, asJSON)
+				state.removedSkills = liteResults(removed)
+			}
 			orphaned := removeOrphanedProfileSkills(out, asJSON, nil, hosts)
 			state.removedSkills = append(state.removedSkills, liteResults(orphaned)...)
 			if !asJSON {
 				fmt.Fprintln(out, "\nCatalog is empty for this org — nothing to install.")
 			}
 		default:
-			// Catalog in hand. Now wipe and install.
-			removed := wipePrevProfileSkills(out, asJSON)
-			state.removedSkills = liteResults(removed)
+			// Catalog in hand. Now wipe and install. The receipt-based
+			// wipe is user-level only (see func doc).
+			if !effectiveProjectScoped {
+				removed := wipePrevProfileSkills(out, asJSON)
+				state.removedSkills = liteResults(removed)
+			}
 			orphaned := removeOrphanedProfileSkills(out, asJSON, skills, hosts)
 			state.removedSkills = append(state.removedSkills, liteResults(orphaned)...)
 			state.catalogSkills = installFetchedCatalog(out, asJSON, skills, hosts)
@@ -131,15 +182,19 @@ func runPostAuthSetup(out io.Writer, asJSON bool, baseURL, token string) postAut
 				fmt.Fprintln(out, "Existing agents left in place. Re-run `praxis login` once the gateway is reachable.")
 			}
 		default:
-			removed, err := uninstallAgentsByPrefix("praxis-")
-			if err != nil {
-				if !asJSON {
-					fmt.Fprintf(out, "Warning: removing previous profile's agents failed: %v\n", err)
+			// Receipt-based agent wipe is user-level only — same
+			// reasoning as the skill wipe above (see func doc).
+			if !effectiveProjectScoped {
+				removed, err := uninstallAgentsByPrefix("praxis-")
+				if err != nil {
+					if !asJSON {
+						fmt.Fprintf(out, "Warning: removing previous profile's agents failed: %v\n", err)
+					}
+				}
+				state.removedAgents = agentLiteResults(removed)
+				if !asJSON && len(removed) > 0 {
+					fmt.Fprintf(out, "\nRemoved %d agent file(s) from previous profile.\n", len(removed))
 				}
-			}
-			state.removedAgents = agentLiteResults(removed)
-			if !asJSON && len(removed) > 0 {
-				fmt.Fprintf(out, "\nRemoved %d agent file(s) from previous profile.\n", len(removed))
 			}
 
 			if len(agents) == 0 {