Samuel Onoja
eb84104940
Publish the guides from this repository to the GitHub Wiki. Organize them into Usage, Configuration and Development, with 15 separate configuration topics and redirects for the former website guide URLs. Add a tabbed-windows guide covering grouping, switching tabs and taking windows out. Document the scrolling indicator's defaults and limits, and link the guide from the README, shortcuts and IPC pages. Update from main, including the latest tabbed-layout changes. Separate Activities setup, configuration and publishing documentation. Review the guide prose with the unslop skill, keeping existing examples and heading links. The wiki workflow uses GitHub's built-in token to publish documentation changes on main. Validation: - 20 documentation tests pass, including README links and Activities/tab-indicator field coverage. - The publisher builds 46 wiki pages; the site build and Python syntax checks pass. - All 115 code examples from main are preserved. - The Python suite passes: 90 tests passed and 31 opt-in integration tests skipped, with the system GI module available.
153 lines
6.8 KiB
Markdown
153 lines
6.8 KiB
Markdown
# Configure Activities
|
||
|
||
Select Morph in **Settings → Panel & Shell** to find **Visible activities** and
|
||
**Show activity count** in its appearance controls. These set the compact slots
|
||
and `+n` badge; hiding the badge still lets you open the full list.
|
||
|
||
Set sources, timing and command rules in the top-level `activities` block in
|
||
`~/.config/ferese/config.kdl`. Merge fields into an existing block rather than
|
||
adding a second one. This example enables the shell hook:
|
||
|
||
```kdl
|
||
activities {
|
||
max-visible 2
|
||
show-badge #true
|
||
start-delay-ms 300
|
||
result-flash-ms 1500
|
||
sources {
|
||
shell-hook #true
|
||
process-watch #false
|
||
notification-bridge #false
|
||
}
|
||
}
|
||
```
|
||
|
||
For hook installation and everyday use, see [Live Activities](../activities.md).
|
||
For the IPC schema and publisher lifetimes, see [Publishing activities](../development/activities.md).
|
||
|
||
## Settings
|
||
|
||
Omitted fields use these built-in defaults. Integer ranges include both endpoints.
|
||
|
||
| Key | Type / accepted values | Default | Meaning |
|
||
| --- | --- | --- | --- |
|
||
| `max-visible` | Integer 1–2 | `2` | Compact activity slots |
|
||
| `show-badge` | Boolean | `#true` | Show `+n` for tasks beyond those slots |
|
||
| `max-total` | Integer 1–128 | `128` | Session record limit, including delayed and completed entries |
|
||
| `owner-ceiling` | Integer 0–255 | `160` | Highest base priority used to rank ordinary activities |
|
||
| `start-delay-ms` | Integer 0–60000 | `300` | Minimum delay before a task appears; a rule can require a longer delay |
|
||
| `result-flash-ms` | Integer 0–10000 | `1500` | How long an eligible completion result remains visible |
|
||
|
||
## Sources
|
||
|
||
Set these booleans inside `activities.sources`:
|
||
|
||
| Key | Built-in default | Meaning |
|
||
| --- | --- | --- |
|
||
| `shell-hook` | `#false` | Accept command start/end events from an installed shell hook |
|
||
| `process-watch` | `#false` | Sample processes when hooks are unavailable; disappearance removes the task without inferring success or failure |
|
||
| `notification-bridge` | `#false` | Show notifications as activities instead of duplicate toasts, respecting Do not disturb and notification popup settings |
|
||
|
||
All three sources are off in the built-in defaults. First-time installer setup
|
||
enables `shell-hook` unless you explicitly set it to `#false`. The process watcher
|
||
and notification bridge stay off unless you enable them.
|
||
|
||
Media comes from MPRIS. Downloads and call statuses need an integration that
|
||
publishes them; microphone or camera use alone does not create a call activity.
|
||
|
||
Changes reload live. Invalid edits leave the last valid configuration in use.
|
||
Check an edit with `ferese --check-config ~/.config/ferese/config.kdl`.
|
||
|
||
## Turn off automatic command detection
|
||
|
||
Set `shell-hook #false` inside `activities.sources`. Leave `process-watch` off
|
||
as well if you don't want process detection. You can still use `feresectl run`
|
||
and direct publishers.
|
||
|
||
To skip shell and Activities setup during installation, pass
|
||
`./scripts/install.sh --no-activities`. This skips setup for that installation;
|
||
it doesn't remove an existing hook or disable an already configured source.
|
||
|
||
## Command rules
|
||
|
||
A named `rule` matches command text and supplies its title, icon, priority and
|
||
completion messages. Rules are matched in declaration order, then unreplaced
|
||
built-ins in Cargo, npm/pnpm, make, git-push, docker-build order. A user rule
|
||
replaces the entire built-in with the same name. One command selects one rule,
|
||
which stays attached to that invocation until it ends.
|
||
|
||
```kdl
|
||
activities {
|
||
max-visible 2
|
||
show-badge #true
|
||
start-delay-ms 300
|
||
result-flash-ms 1500
|
||
sources {
|
||
shell-hook #true
|
||
process-watch #false
|
||
notification-bridge #false
|
||
}
|
||
rule "cargo" {
|
||
match #"^cargo (build|check|test|run|clippy)\b"#
|
||
title "cargo {1}"
|
||
icon "hammer"
|
||
priority 100
|
||
progress "indeterminate"
|
||
min-duration-ms 1500
|
||
ignore-parents "rust-analyzer"
|
||
dedupe-by "cwd"
|
||
flash-on-fail #true
|
||
result ok="Finished" fail="Command failed"
|
||
}
|
||
}
|
||
```
|
||
|
||
These defaults apply to a new custom rule. Built-in rules have their own values,
|
||
shown in the [source catalog](../../crates/ferese-config/activities.kdl).
|
||
|
||
| Key | Type / accepted values | Default for a custom rule |
|
||
| --- | --- | --- |
|
||
| Rule name | String, up to 256 UTF-8 bytes, no control characters; unique | Required positional argument |
|
||
| `match` | Valid regular expression, up to 2048 UTF-8 bytes | Required |
|
||
| `title` | String, up to 256 UTF-8 bytes, no control characters | Required |
|
||
| `icon` | Symbolic name, up to 64 ASCII letters, digits or hyphens | `"ferese"` |
|
||
| `priority` | Integer 0–255; ranking caps it at `owner-ceiling` | `100` |
|
||
| `progress` | `"indeterminate"` or `"cargo-json"` | `"indeterminate"` |
|
||
| `min-duration-ms` | Integer 0–60000 | `0` |
|
||
| `ignore-parents` | Up to 16 names, each up to 128 UTF-8 bytes | No ignored parents |
|
||
| `dedupe-by` | `"cwd"`, or omit for no grouping | Unset |
|
||
| `flash-on-fail` | Boolean | `#true` |
|
||
| `result.ok` | String, up to 256 UTF-8 bytes, no control characters | `"Finished"` |
|
||
| `result.fail` | String, up to 256 UTF-8 bytes, no control characters | `"Command failed"` |
|
||
|
||
Use `result ok="Finished" fail="Command failed"` inside the rule to change both
|
||
messages. If you provide `result`, both fields are required. Title placeholders
|
||
refer to regex captures: `{0}` is the whole match, `{1}` the first group, and so
|
||
on. Invalid capture references reject the configuration. An expanded title over
|
||
256 bytes or containing control characters is discarded during matching.
|
||
|
||
`ignore-parents` accepts multiple names in one node, such as
|
||
`ignore-parents "rust-analyzer" "editor"`. `dedupe-by "cwd"` groups tasks by a
|
||
hash of the working directory within the same owner and rule. Invocations retain
|
||
independent lifetimes, and progress is never averaged.
|
||
|
||
`progress "cargo-json"` enables the adapter for matching `feresectl run`
|
||
commands. Shell hooks do not wrap commands or parse their output automatically;
|
||
see [Cargo progress](../activities.md#cargo-progress).
|
||
|
||
## Visibility and matching limits
|
||
|
||
The visibility delay is the larger of `start-delay-ms` and `min-duration-ms`.
|
||
Completion before that delay, including failure, never flashes. Eligible results
|
||
last 1500 ms by default; `flash-on-fail #false` removes failures directly.
|
||
|
||
At most 64 rules may remain after unreplaced built-ins are added. Command input
|
||
is limited to 4096 UTF-8 bytes, working directories to 1024 bytes and parent lists
|
||
to 16 entries. The matcher sets a 256 KiB compiled-size limit and a 256 KiB DFA-size limit.
|
||
Command and cwd metadata are used only during matching; nonmatches are discarded
|
||
and never logged.
|
||
|
||
Configuration is validated before application; an invalid reload preserves the
|
||
last valid configuration. Diagnostics include source offsets for activity
|
||
configuration errors.
|