docs: add SYNOPSIS/DESCRIPTION doc blocks to session hook scripts and index entries

docs/fish-config.index

@@ -11,6 +11,10 @@ synopsis=# SYNOPSIS
 description=# DESCRIPTION
 toc=# TABLE OF CONTENTS
 contents=# TABLE OF CONTENTS
+autopair=# DESCRIPTION
+puffer=# DESCRIPTION
+puffer-fish=# DESCRIPTION
+logging-events=# DESCRIPTION
 
 # ── Section 1: Configuration Variables ───────────────────────
 variables=# 1. CONFIGURATION VARIABLES

functions/save_antigravity_session.fish

@@ -3,6 +3,28 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
+# SYNOPSIS
+#   Invoked as an Antigravity session hook; reads JSON from stdin.
+#
+# DESCRIPTION
+#   Hook script called by the Antigravity CLI (agy) on session start.
+#   Reads a JSON payload from stdin, extracts the session_id field, and
+#   writes it to .antigravity_session in the current directory. Ensures
+#   that file is excluded via .gitignore. Sets the universal variable
+#   LAST_ANTIGRAVITY_SESSION for cross-terminal access. Falls back to a
+#   no-op (emitting "{}") when python3 is unavailable (Convention §6).
+#
+# ARGUMENTS
+#   stdin  JSON payload from the Antigravity CLI containing a "session_id" key
+#
+# RETURNS
+#   0  Always; emits "{}" to stdout as required by the hook contract
+#
+# EXAMPLE
+#   echo '{"session_id":"abc123"}' | fish save_antigravity_session.fish
+#   cat .antigravity_session   # → abc123
+#   echo $LAST_ANTIGRAVITY_SESSION   # → abc123
+
 # 1. Read the JSON from stdin
 set -l input (cat)
 

functions/save_claude_session.fish

@@ -3,6 +3,28 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
+# SYNOPSIS
+#   Invoked as a Claude Code session hook; reads JSON from stdin.
+#
+# DESCRIPTION
+#   Hook script called by Claude Code on session start. Reads a JSON payload
+#   from stdin, extracts the session_id field, and writes it to .claude_session
+#   in the current directory. Ensures that file is excluded via .gitignore.
+#   Sets the universal variable LAST_CLAUDE_SESSION for cross-terminal access.
+#   Falls back to a no-op (emitting "{}") when python3 is unavailable
+#   (Convention §6).
+#
+# ARGUMENTS
+#   stdin  JSON payload from Claude Code containing a "session_id" key
+#
+# RETURNS
+#   0  Always; emits "{}" to stdout as required by the hook contract
+#
+# EXAMPLE
+#   echo '{"session_id":"abc123"}' | fish save_claude_session.fish
+#   cat .claude_session   # → abc123
+#   echo $LAST_CLAUDE_SESSION   # → abc123
+
 # 1. Read input and extract session ID
 #    python3 parses the session_id out of the hook's JSON payload. If it is
 #    unavailable we emit valid empty JSON and skip session tracking rather