update

README.md

@@ -1 +1,51 @@
-Shell agnostic shell startup commands.
+# Shared shell profile
+
+This repository owns the login environment and interactive commands intended
+to be shared by Bourne-family shells.
+
+"Shared" means shells capable of reading POSIX-style `sh`, such as `sh`, Bash,
+Dash and—with appropriate compatibility—Zsh. It does not mean that the same
+file can be sourced directly by shells with different languages, such as Fish
+or Nushell.
+
+## Responsibilities
+
+- Install `~/.profile` as a symlink into this repository.
+- Define XDG locations and general editor/browser environment variables.
+- Construct PATH idempotently for language and user-level executable paths.
+- Load environment setup that is portable at login, such as Cargo's `env` file.
+- Provide common aliases and small interactive functions that are useful
+  across supported Bourne-family shells.
+
+## Boundaries
+
+The `profile` file must remain quiet, idempotent and safe for a POSIX shell to
+source during login. It must not print an alias catalogue, configure a prompt,
+perform interactive terminal operations or start background work.
+
+Interactive shells should source `aliases.sh` from their own RC file. The
+login profile deliberately does not source it, because login profiles may also
+run in non-interactive sessions.
+
+Shell-specific prompt, history, completion and initialization belongs in the
+corresponding shell repository, currently `bash`. User services and timers
+belong in the separate `systemd` repository.
+
+## Files
+
+- `profile`: portable login environment and PATH construction.
+- `aliases.sh`: common interactive aliases and helper functions.
+- `commands.tsv`: curated command descriptions and startup visibility.
+- `commands.README.md`: format and maintenance instructions for `commands.tsv`.
+- `install.sh`: installs the `~/.profile` symlink.
+
+## Alias portability
+
+`aliases.sh` is intended to become POSIX-compatible for Bourne-family shells,
+but it currently contains some Bash-oriented constructs. Before another shell
+sources it, replace or isolate uses of `source`, `disown`, `local`, `echo -e`,
+Bash-style `cd --`, and the transitional `debug.log` alias name.
+
+External commands remain platform-specific by design: aliases for Pacman,
+systemd, GNU utilities and local applications target this Arch Linux setup.
+Syntax portability does not imply operating-system portability.