Add fessctl agent skill (v0.1.0)

skills/fessctl/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: fessctl
+description: Operate Fess via fessctl CLI (admin API client). Use when managing webconfigs, file/data configs, schedulers, users/roles/groups, dictionaries, access tokens, or any Fess admin resource from Claude. Covers CRUD on 22 resource types and cross-feature workflows like initial crawl setup.
+license: Apache-2.0
+version: 0.1.0
+---
+
+# fessctl
+
+`fessctl` is the Python CLI for the Fess admin REST API. This skill teaches Claude to detect/run fessctl, authenticate, and operate every supported resource.
+
+## Detection (run in this order)
+
+1. `command -v fessctl` → use it directly (covers `pipx install fessctl`, `uv tool install fessctl`, manual `uv pip install -e .`, or any future package-manager install).
+2. Fall back to `docker run --rm -e FESS_ENDPOINT -e FESS_ACCESS_TOKEN -e FESS_VERSION ghcr.io/codelibs/fessctl:<tag>`.
+
+See `references/installation.md` for the exact wrappers.
+
+## Required environment
+
+- `FESS_ENDPOINT` (default `http://localhost:8080`)
+- `FESS_ACCESS_TOKEN` (required for any non-`ping` call)
+- `FESS_VERSION` (e.g. `15.6.0`; must match the target Fess server)
+
+See `references/authentication.md` for token issuance.
+
+## Always do this first
+
+Before invoking any subcommand the assistant has not seen recently, run `fessctl <subcommand> --help` to confirm the current option surface — fessctl evolves with Fess and `--help` is the source of truth.
+
+## Index — common references
+
+| Topic | File |
+|-------|------|
+| Install / detection / wrappers | references/installation.md |
+| Auth, tokens, env vars         | references/authentication.md |
+| Output formats (JSON/YAML/MD)  | references/output-formats.md |
+| CRUD conventions, IDs, paging  | references/conventions.md |
+| Common errors and recovery     | references/troubleshooting.md |
+| Multi-feature recipes          | references/workflows.md |
+
+## Resources — per-feature reference
+
+Each file documents one Fess admin feature: what it is, when to use it, fessctl subcommand surface, JSON shape, gotchas, and examples.
+
+| Feature | File |
+|---------|------|
+| Web crawl configs        | references/features/webconfig.md |
+| File crawl configs       | references/features/fileconfig.md |
+| Datastore configs        | references/features/dataconfig.md |
+| Web auth credentials     | references/features/webauth.md |
+| File auth credentials    | references/features/fileauth.md |
+| Crawl scheduler / jobs   | references/features/scheduler.md |
+| Job logs                 | references/features/joblog.md |
+| Crawling info            | references/features/crawlinginfo.md |
+| Users                    | references/features/user.md |
+| Roles                    | references/features/role.md |
+| Groups                   | references/features/group.md |
+| Access tokens            | references/features/accesstoken.md |
+| Label types              | references/features/labeltype.md |
+| Key match                | references/features/keymatch.md |
+| Boost document           | references/features/boostdoc.md |
+| Elevate word             | references/features/elevateword.md |
+| Bad word                 | references/features/badword.md |
+| Related content          | references/features/relatedcontent.md |
+| Related query            | references/features/relatedquery.md |
+| Path mapping             | references/features/pathmap.md |
+| Duplicate host           | references/features/duplicatehost.md |
+| Request header           | references/features/reqheader.md |

skills/fessctl/references/authentication.md

@@ -0,0 +1,82 @@
+# Authenticating with Fess
+
+Every fessctl call other than `ping` is authenticated with a Fess access token sent as a Bearer header. This file covers the three required environment variables, how to issue a token, where to keep it, and how to verify the wiring.
+
+## Required environment variables
+
+| Variable | Required | Default | Notes |
+|----------|----------|---------|-------|
+| `FESS_ENDPOINT`     | optional | `http://localhost:8080`    | Base URL of the target Fess server. Include scheme; do not include a trailing `/`. |
+| `FESS_ACCESS_TOKEN` | **yes** for any non-`ping` call | none | Bearer token issued from the Fess admin UI or via `fessctl accesstoken create`. |
+| `FESS_VERSION`      | optional | `15.4.0` (as of fessctl 0.1.0) | Must match the major.minor of the target Fess server so request shapes line up. Set it explicitly — do not rely on the default. |
+
+Defaults live in `src/fessctl/config/settings.py`. The defaults are conservative and may lag the latest Fess release; for any non-trivial work, set `FESS_ENDPOINT` and `FESS_VERSION` explicitly.
+
+## Issuing an access token
+
+### Via the admin UI
+
+1. Browse to `${FESS_ENDPOINT}/admin/` and sign in with an admin account.
+2. Open **System → Access Token**.
+3. Click **Create New**, give the token a name (e.g. `claude-cli`), and pick a parameter name plus the permissions it should grant. Permissions are Fess permission strings of the form `{role}<role-name>`, `{group}<group-name>`, or `{user}<user-name>` — for full administrative access bind the token to a role that already has admin rights, for example `{role}admin`. The exact syntax is documented in `fess-docs/en/15.6/admin/accesstoken-guide.rst`.
+4. Save and copy the generated token value. It is shown only once.
+
+### Via fessctl (after you already have one admin token)
+
+```bash
+fessctl accesstoken create \
+  --name claude-cli \
+  --permission "{role}admin"          # repeat --permission to grant more
+```
+
+See `references/features/accesstoken.md` for the full subcommand surface (list, get, update, delete).
+
+## Where to put the token
+
+Pick the option that matches how you run fessctl.
+
+- **direnv (`.envrc` per project):**
+  ```bash
+  export FESS_ENDPOINT=http://localhost:8080
+  export FESS_ACCESS_TOKEN=eyJhbGciOi...
+  export FESS_VERSION=15.6.0
+  ```
+  Add `.envrc` to `.gitignore`. Run `direnv allow` to activate.
+
+- **Shell rc (`~/.zshrc`, `~/.bashrc`):** acceptable for personal machines, but prefer per-project `.envrc` so different Fess environments do not collide.
+
+- **GitHub Codespaces / Actions:** store as encrypted secrets and inject via `env:` in the workflow.
+
+- **Docker invocation:** pass `-e FESS_ACCESS_TOKEN` (the host environment variable is forwarded to the container — do **not** put the token on the command line where it would land in shell history).
+
+Never commit a token to git, and never include it in chat output, log files, or documentation examples.
+
+## Token scope and expiry
+
+Fess access tokens are bearer tokens. The token's permissions are fixed at creation time; rotating permissions means issuing a new token and deleting the old one. Tokens do not auto-rotate. If a token leaks, delete it immediately via:
+
+```bash
+fessctl accesstoken list --output json \
+  | jq '.response.settings[] | select(.name=="claude-cli")'
+fessctl accesstoken delete <id>
+```
+
+Most fessctl subcommands require admin-equivalent permission. A token bound to a non-admin role will succeed at `ping` and may succeed at some read-only `list` operations but will fail with `403 Forbidden` on `create`/`update`/`delete`.
+
+## Smoke test
+
+The canonical wired-up check is two commands:
+
+```bash
+fessctl ping                         # no token required
+fessctl user list --size 1           # token required, admin permission required
+```
+
+Expected:
+
+- `ping` succeeds when `FESS_ENDPOINT` is reachable.
+- `user list --size 1` succeeds when both `FESS_ACCESS_TOKEN` and `FESS_VERSION` are correct and the token has admin permission.
+
+## Common 401 / 403 causes
+
+If `user list` fails after `ping` succeeds, the token is the problem. See `references/troubleshooting.md` for the full diagnostic flow; the short list is: token unset, token typo, token expired or revoked, or token issued for a role that lacks admin permissions.