Recovered 70 prior commits from Gitea mirror and resolved divergent history using --allow-unrelated-histories. Integrated 16 recent local commits via patch. Applied targeted technical fixes: added explicit bash shell declaration in shellcheck YAML configuration (commit 693caff) and targeted SC2120 disables in modules/utils.sh (commit 3614b56). All verifications passed: shellcheck compliance, bash syntax check (bash -n), and BATS test suite passing cleanly. Symmetrically synchronized repository state across GitHub and Gitea.

2026-10-31 13:08:06 +00:00 · 2026-10-14 21:40:12 -05:00
parent 89233b0750
commit f735b54331
25 changed files with 358 additions and 1424 deletions
@@ -0,0 +1,18 @@
 name: CI
 on: [push, pull_request]
 jobs:
  lint-and-test:
    runs-on: ubuntu-latest
    container: debian:trixie
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Install bats + shellcheck
        run: apt-get update && apt-get install -y bats shellcheck
      - name: Shellcheck (entry point + all modules)
        shell: bash
        run: |
          shopt -s globstar
          shellcheck --severity=warning debianito.sh modules/**/*.sh
      - name: BATS test suite
        run: bats tests/
@@ -0,0 +1 @@
 tests/.tmp/
@@ -1,674 +0,0 @@
                    GNU GENERAL PUBLIC LICENSE
                       Version 3, 29 June 2007
 Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
 Everyone is permitted to copy and distribute verbatim copies
 of this license document, but changing it is not allowed.
                            Preamble
  The GNU General Public License is a free, copyleft license for
 software and other kinds of works.
  The licenses for most software and other practical works are designed
 to take away your freedom to share and change the works.  By contrast,
 the GNU General Public License is intended to guarantee your freedom to
 share and change all versions of a program--to make sure it remains free
 software for all its users.  We, the Free Software Foundation, use the
 GNU General Public License for most of our software; it applies also to
 any other work released this way by its authors.  You can apply it to
 your programs, too.
  When we speak of free software, we are referring to freedom, not
 price.  Our General Public Licenses are designed to make sure that you
 have the freedom to distribute copies of free software (and charge for
 them if you wish), that you receive source code or can get it if you
 want it, that you can change the software or use pieces of it in new
 free programs, and that you know you can do these things.
  To protect your rights, we need to prevent others from denying you
 these rights or asking you to surrender the rights.  Therefore, you have
 certain responsibilities if you distribute copies of the software, or if
 you modify it: responsibilities to respect the freedom of others.
  For example, if you distribute copies of such a program, whether
 gratis or for a fee, you must pass on to the recipients the same
 freedoms that you received.  You must make sure that they, too, receive
 or can get the source code.  And you must show them these terms so they
 know their rights.
  Developers that use the GNU GPL protect your rights with two steps:
 (1) assert copyright on the software, and (2) offer you this License
 giving you legal permission to copy, distribute and/or modify it.
  For the developers' and authors' protection, the GPL clearly explains
 that there is no warranty for this free software.  For both users' and
 authors' sake, the GPL requires that modified versions be marked as
 changed, so that their problems will not be attributed erroneously to
 authors of previous versions.
  Some devices are designed to deny users access to install or run
 modified versions of the software inside them, although the manufacturer
 can do so.  This is fundamentally incompatible with the aim of
 protecting users' freedom to change the software.  The systematic
 pattern of such abuse occurs in the area of products for individuals to
 use, which is precisely where it is most unacceptable.  Therefore, we
 have designed this version of the GPL to prohibit the practice for those
 products.  If such problems arise substantially in other domains, we
 stand ready to extend this provision to those domains in future versions
 of the GPL, as needed to protect the freedom of users.
  Finally, every program is threatened constantly by software patents.
 States should not allow patents to restrict development and use of
 software on general-purpose computers, but in those that do, we wish to
 avoid the special danger that patents applied to a free program could
 make it effectively proprietary.  To prevent this, the GPL assures that
 patents cannot be used to render the program non-free.
  The precise terms and conditions for copying, distribution and
 modification follow.
                       TERMS AND CONDITIONS
  0. Definitions.
  "This License" refers to version 3 of the GNU General Public License.
  "Copyright" also means copyright-like laws that apply to other kinds of
 works, such as semiconductor masks.
  "The Program" refers to any copyrightable work licensed under this
 License.  Each licensee is addressed as "you".  "Licensees" and
 "recipients" may be individuals or organizations.
  To "modify" a work means to copy from or adapt all or part of the work
 in a fashion requiring copyright permission, other than the making of an
 exact copy.  The resulting work is called a "modified version" of the
 earlier work or a work "based on" the earlier work.
  A "covered work" means either the unmodified Program or a work based
 on the Program.
  To "propagate" a work means to do anything with it that, without
 permission, would make you directly or secondarily liable for
 infringement under applicable copyright law, except executing it on a
 computer or modifying a private copy.  Propagation includes copying,
 distribution (with or without modification), making available to the
 public, and in some countries other activities as well.
  To "convey" a work means any kind of propagation that enables other
 parties to make or receive copies.  Mere interaction with a user through
 a computer network, with no transfer of a copy, is not conveying.
  An interactive user interface displays "Appropriate Legal Notices"
 to the extent that it includes a convenient and prominently visible
 feature that (1) displays an appropriate copyright notice, and (2)
 tells the user that there is no warranty for the work (except to the
 extent that warranties are provided), that licensees may convey the
 work under this License, and how to view a copy of this License.  If
 the interface presents a list of user commands or options, such as a
 menu, a prominent item in the list meets this criterion.
  1. Source Code.
  The "source code" for a work means the preferred form of the work
 for making modifications to it.  "Object code" means any non-source
 form of a work.
  A "Standard Interface" means an interface that either is an official
 standard defined by a recognized standards body, or, in the case of
 interfaces specified for a particular programming language, one that
 is widely used among developers working in that language.
  The "System Libraries" of an executable work include anything, other
 than the work as a whole, that (a) is included in the normal form of
 packaging a Major Component, but which is not part of that Major
 Component, and (b) serves only to enable use of the work with that
 Major Component, or to implement a Standard Interface for which an
 implementation is available to the public in source code form.  A
 "Major Component", in this context, means a major essential component
 (kernel, window system, and so on) of the specific operating system
 (if any) on which the executable work runs, or a compiler used to
 produce the work, or an object code interpreter used to run it.
  The "Corresponding Source" for a work in object code form means all
 the source code needed to generate, install, and (for an executable
 work) run the object code and to modify the work, including scripts to
 control those activities.  However, it does not include the work's
 System Libraries, or general-purpose tools or generally available free
 programs which are used unmodified in performing those activities but
 which are not part of the work.  For example, Corresponding Source
 includes interface definition files associated with source files for
 the work, and the source code for shared libraries and dynamically
 linked subprograms that the work is specifically designed to require,
 such as by intimate data communication or control flow between those
 subprograms and other parts of the work.
  The Corresponding Source need not include anything that users
 can regenerate automatically from other parts of the Corresponding
 Source.
  The Corresponding Source for a work in source code form is that
 same work.
  2. Basic Permissions.
  All rights granted under this License are granted for the term of
 copyright on the Program, and are irrevocable provided the stated
 conditions are met.  This License explicitly affirms your unlimited
 permission to run the unmodified Program.  The output from running a
 covered work is covered by this License only if the output, given its
 content, constitutes a covered work.  This License acknowledges your
 rights of fair use or other equivalent, as provided by copyright law.
  You may make, run and propagate covered works that you do not
 convey, without conditions so long as your license otherwise remains
 in force.  You may convey covered works to others for the sole purpose
 of having them make modifications exclusively for you, or provide you
 with facilities for running those works, provided that you comply with
 the terms of this License in conveying all material for which you do
 not control copyright.  Those thus making or running the covered works
 for you must do so exclusively on your behalf, under your direction
 and control, on terms that prohibit them from making any copies of
 your copyrighted material outside their relationship with you.
  Conveying under any other circumstances is permitted solely under
 the conditions stated below.  Sublicensing is not allowed; section 10
 makes it unnecessary.
  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
  No covered work shall be deemed part of an effective technological
 measure under any applicable law fulfilling obligations under article
 11 of the WIPO copyright treaty adopted on 20 December 1996, or
 similar laws prohibiting or restricting circumvention of such
 measures.
  When you convey a covered work, you waive any legal power to forbid
 circumvention of technological measures to the extent such circumvention
 is effected by exercising rights under this License with respect to
 the covered work, and you disclaim any intention to limit operation or
 modification of the work as a means of enforcing, against the work's
 users, your or third parties' legal rights to forbid circumvention of
 technological measures.
  4. Conveying Verbatim Copies.
  You may convey verbatim copies of the Program's source code as you
 receive it, in any medium, provided that you conspicuously and
 appropriately publish on each copy an appropriate copyright notice;
 keep intact all notices stating that this License and any
 non-permissive terms added in accord with section 7 apply to the code;
 keep intact all notices of the absence of any warranty; and give all
 recipients a copy of this License along with the Program.
  You may charge any price or no price for each copy that you convey,
 and you may offer support or warranty protection for a fee.
  5. Conveying Modified Source Versions.
  You may convey a work based on the Program, or the modifications to
 produce it from the Program, in the form of source code under the
 terms of section 4, provided that you also meet all of these conditions:
    a) The work must carry prominent notices stating that you modified
    it, and giving a relevant date.
    b) The work must carry prominent notices stating that it is
    released under this License and any conditions added under section
    7.  This requirement modifies the requirement in section 4 to
    "keep intact all notices".
    c) You must license the entire work, as a whole, under this
    License to anyone who comes into possession of a copy.  This
    License will therefore apply, along with any applicable section 7
    additional terms, to the whole of the work, and all its parts,
    regardless of how they are packaged.  This License gives no
    permission to license the work in any other way, but it does not
    invalidate such permission if you have separately received it.
    d) If the work has interactive user interfaces, each must display
    Appropriate Legal Notices; however, if the Program has interactive
    interfaces that do not display Appropriate Legal Notices, your
    work need not make them do so.
  A compilation of a covered work with other separate and independent
 works, which are not by their nature extensions of the covered work,
 and which are not combined with it such as to form a larger program,
 in or on a volume of a storage or distribution medium, is called an
 "aggregate" if the compilation and its resulting copyright are not
 used to limit the access or legal rights of the compilation's users
 beyond what the individual works permit.  Inclusion of a covered work
 in an aggregate does not cause this License to apply to the other
 parts of the aggregate.
  6. Conveying Non-Source Forms.
  You may convey a covered work in object code form under the terms
 of sections 4 and 5, provided that you also convey the
 machine-readable Corresponding Source under the terms of this License,
 in one of these ways:
    a) Convey the object code in, or embodied in, a physical product
    (including a physical distribution medium), accompanied by the
    Corresponding Source fixed on a durable physical medium
    customarily used for software interchange.
    b) Convey the object code in, or embodied in, a physical product
    (including a physical distribution medium), accompanied by a
    written offer, valid for at least three years and valid for as
    long as you offer spare parts or customer support for that product
    model, to give anyone who possesses the object code either (1) a
    copy of the Corresponding Source for all the software in the
    product that is covered by this License, on a durable physical
    medium customarily used for software interchange, for a price no
    more than your reasonable cost of physically performing this
    conveying of source, or (2) access to copy the
    Corresponding Source from a network server at no charge.
    c) Convey individual copies of the object code with a copy of the
    written offer to provide the Corresponding Source.  This
    alternative is allowed only occasionally and noncommercially, and
    only if you received the object code with such an offer, in accord
    with subsection 6b.
    d) Convey the object code by offering access from a designated
    place (gratis or for a charge), and offer equivalent access to the
    Corresponding Source in the same way through the same place at no
    further charge.  You need not require recipients to copy the
    Corresponding Source along with the object code.  If the place to
    copy the object code is a network server, the Corresponding Source
    may be on a different server (operated by you or a third party)
    that supports equivalent copying facilities, provided you maintain
    clear directions next to the object code saying where to find the
    Corresponding Source.  Regardless of what server hosts the
    Corresponding Source, you remain obligated to ensure that it is
    available for as long as needed to satisfy these requirements.
    e) Convey the object code using peer-to-peer transmission, provided
    you inform other peers where the object code and Corresponding
    Source of the work are being offered to the general public at no
    charge under subsection 6d.
  A separable portion of the object code, whose source code is excluded
 from the Corresponding Source as a System Library, need not be
 included in conveying the object code work.
  A "User Product" is either (1) a "consumer product", which means any
 tangible personal property which is normally used for personal, family,
 or household purposes, or (2) anything designed or sold for incorporation
 into a dwelling.  In determining whether a product is a consumer product,
 doubtful cases shall be resolved in favor of coverage.  For a particular
 product received by a particular user, "normally used" refers to a
 typical or common use of that class of product, regardless of the status
 of the particular user or of the way in which the particular user
 actually uses, or expects or is expected to use, the product.  A product
 is a consumer product regardless of whether the product has substantial
 commercial, industrial or non-consumer uses, unless such uses represent
 the only significant mode of use of the product.
  "Installation Information" for a User Product means any methods,
 procedures, authorization keys, or other information required to install
 and execute modified versions of a covered work in that User Product from
 a modified version of its Corresponding Source.  The information must
 suffice to ensure that the continued functioning of the modified object
 code is in no case prevented or interfered with solely because
 modification has been made.
  If you convey an object code work under this section in, or with, or
 specifically for use in, a User Product, and the conveying occurs as
 part of a transaction in which the right of possession and use of the
 User Product is transferred to the recipient in perpetuity or for a
 fixed term (regardless of how the transaction is characterized), the
 Corresponding Source conveyed under this section must be accompanied
 by the Installation Information.  But this requirement does not apply
 if neither you nor any third party retains the ability to install
 modified object code on the User Product (for example, the work has
 been installed in ROM).
  The requirement to provide Installation Information does not include a
 requirement to continue to provide support service, warranty, or updates
 for a work that has been modified or installed by the recipient, or for
 the User Product in which it has been modified or installed.  Access to a
 network may be denied when the modification itself materially and
 adversely affects the operation of the network or violates the rules and
 protocols for communication across the network.
  Corresponding Source conveyed, and Installation Information provided,
 in accord with this section must be in a format that is publicly
 documented (and with an implementation available to the public in
 source code form), and must require no special password or key for
 unpacking, reading or copying.
  7. Additional Terms.
  "Additional permissions" are terms that supplement the terms of this
 License by making exceptions from one or more of its conditions.
 Additional permissions that are applicable to the entire Program shall
 be treated as though they were included in this License, to the extent
 that they are valid under applicable law.  If additional permissions
 apply only to part of the Program, that part may be used separately
 under those permissions, but the entire Program remains governed by
 this License without regard to the additional permissions.
  When you convey a copy of a covered work, you may at your option
 remove any additional permissions from that copy, or from any part of
 it.  (Additional permissions may be written to require their own
 removal in certain cases when you modify the work.)  You may place
 additional permissions on material, added by you to a covered work,
 for which you have or can give appropriate copyright permission.
  Notwithstanding any other provision of this License, for material you
 add to a covered work, you may (if authorized by the copyright holders of
 that material) supplement the terms of this License with terms:
    a) Disclaiming warranty or limiting liability differently from the
    terms of sections 15 and 16 of this License; or
    b) Requiring preservation of specified reasonable legal notices or
    author attributions in that material or in the Appropriate Legal
    Notices displayed by works containing it; or
    c) Prohibiting misrepresentation of the origin of that material, or
    requiring that modified versions of such material be marked in
    reasonable ways as different from the original version; or
    d) Limiting the use for publicity purposes of names of licensors or
    authors of the material; or
    e) Declining to grant rights under trademark law for use of some
    trade names, trademarks, or service marks; or
    f) Requiring indemnification of licensors and authors of that
    material by anyone who conveys the material (or modified versions of
    it) with contractual assumptions of liability to the recipient, for
    any liability that these contractual assumptions directly impose on
    those licensors and authors.
  All other non-permissive additional terms are considered "further
 restrictions" within the meaning of section 10.  If the Program as you
 received it, or any part of it, contains a notice stating that it is
 governed by this License along with a term that is a further
 restriction, you may remove that term.  If a license document contains
 a further restriction but permits relicensing or conveying under this
 License, you may add to a covered work material governed by the terms
 of that license document, provided that the further restriction does
 not survive such relicensing or conveying.
  If you add terms to a covered work in accord with this section, you
 must place, in the relevant source files, a statement of the
 additional terms that apply to those files, or a notice indicating
 where to find the applicable terms.
  Additional terms, permissive or non-permissive, may be stated in the
 form of a separately written license, or stated as exceptions;
 the above requirements apply either way.
  8. Termination.
  You may not propagate or modify a covered work except as expressly
 provided under this License.  Any attempt otherwise to propagate or
 modify it is void, and will automatically terminate your rights under
 this License (including any patent licenses granted under the third
 paragraph of section 11).
  However, if you cease all violation of this License, then your
 license from a particular copyright holder is reinstated (a)
 provisionally, unless and until the copyright holder explicitly and
 finally terminates your license, and (b) permanently, if the copyright
 holder fails to notify you of the violation by some reasonable means
 prior to 60 days after the cessation.
  Moreover, your license from a particular copyright holder is
 reinstated permanently if the copyright holder notifies you of the
 violation by some reasonable means, this is the first time you have
 received notice of violation of this License (for any work) from that
 copyright holder, and you cure the violation prior to 30 days after
 your receipt of the notice.
  Termination of your rights under this section does not terminate the
 licenses of parties who have received copies or rights from you under
 this License.  If your rights have been terminated and not permanently
 reinstated, you do not qualify to receive new licenses for the same
 material under section 10.
  9. Acceptance Not Required for Having Copies.
  You are not required to accept this License in order to receive or
 run a copy of the Program.  Ancillary propagation of a covered work
 occurring solely as a consequence of using peer-to-peer transmission
 to receive a copy likewise does not require acceptance.  However,
 nothing other than this License grants you permission to propagate or
 modify any covered work.  These actions infringe copyright if you do
 not accept this License.  Therefore, by modifying or propagating a
 covered work, you indicate your acceptance of this License to do so.
  10. Automatic Licensing of Downstream Recipients.
  Each time you convey a covered work, the recipient automatically
 receives a license from the original licensors, to run, modify and
 propagate that work, subject to this License.  You are not responsible
 for enforcing compliance by third parties with this License.
  An "entity transaction" is a transaction transferring control of an
 organization, or substantially all assets of one, or subdividing an
 organization, or merging organizations.  If propagation of a covered
 work results from an entity transaction, each party to that
 transaction who receives a copy of the work also receives whatever
 licenses to the work the party's predecessor in interest had or could
 give under the previous paragraph, plus a right to possession of the
 Corresponding Source of the work from the predecessor in interest, if
 the predecessor has it or can get it with reasonable efforts.
  You may not impose any further restrictions on the exercise of the
 rights granted or affirmed under this License.  For example, you may
 not impose a license fee, royalty, or other charge for exercise of
 rights granted under this License, and you may not initiate litigation
 (including a cross-claim or counterclaim in a lawsuit) alleging that
 any patent claim is infringed by making, using, selling, offering for
 sale, or importing the Program or any portion of it.
  11. Patents.
  A "contributor" is a copyright holder who authorizes use under this
 License of the Program or a work on which the Program is based.  The
 work thus licensed is called the contributor's "contributor version".
  A contributor's "essential patent claims" are all patent claims
 owned or controlled by the contributor, whether already acquired or
 hereafter acquired, that would be infringed by some manner, permitted
 by this License, of making, using, or selling its contributor version,
 but do not include claims that would be infringed only as a
 consequence of further modification of the contributor version.  For
 purposes of this definition, "control" includes the right to grant
 patent sublicenses in a manner consistent with the requirements of
 this License.
  Each contributor grants you a non-exclusive, worldwide, royalty-free
 patent license under the contributor's essential patent claims, to
 make, use, sell, offer for sale, import and otherwise run, modify and
 propagate the contents of its contributor version.
  In the following three paragraphs, a "patent license" is any express
 agreement or commitment, however denominated, not to enforce a patent
 (such as an express permission to practice a patent or covenant not to
 sue for patent infringement).  To "grant" such a patent license to a
 party means to make such an agreement or commitment not to enforce a
 patent against the party.
  If you convey a covered work, knowingly relying on a patent license,
 and the Corresponding Source of the work is not available for anyone
 to copy, free of charge and under the terms of this License, through a
 publicly available network server or other readily accessible means,
 then you must either (1) cause the Corresponding Source to be so
 available, or (2) arrange to deprive yourself of the benefit of the
 patent license for this particular work, or (3) arrange, in a manner
 consistent with the requirements of this License, to extend the patent
 license to downstream recipients.  "Knowingly relying" means you have
 actual knowledge that, but for the patent license, your conveying the
 covered work in a country, or your recipient's use of the covered work
 in a country, would infringe one or more identifiable patents in that
 country that you have reason to believe are valid.
  If, pursuant to or in connection with a single transaction or
 arrangement, you convey, or propagate by procuring conveyance of, a
 covered work, and grant a patent license to some of the parties
 receiving the covered work authorizing them to use, propagate, modify
 or convey a specific copy of the covered work, then the patent license
 you grant is automatically extended to all recipients of the covered
 work and works based on it.
  A patent license is "discriminatory" if it does not include within
 the scope of its coverage, prohibits the exercise of, or is
 conditioned on the non-exercise of one or more of the rights that are
 specifically granted under this License.  You may not convey a covered
 work if you are a party to an arrangement with a third party that is
 in the business of distributing software, under which you make payment
 to the third party based on the extent of your activity of conveying
 the work, and under which the third party grants, to any of the
 parties who would receive the covered work from you, a discriminatory
 patent license (a) in connection with copies of the covered work
 conveyed by you (or copies made from those copies), or (b) primarily
 for and in connection with specific products or compilations that
 contain the covered work, unless you entered into that arrangement,
 or that patent license was granted, prior to 28 March 2007.
  Nothing in this License shall be construed as excluding or limiting
 any implied license or other defenses to infringement that may
 otherwise be available to you under applicable patent law.
  12. No Surrender of Others' Freedom.
  If conditions are imposed on you (whether by court order, agreement or
 otherwise) that contradict the conditions of this License, they do not
 excuse you from the conditions of this License.  If you cannot convey a
 covered work so as to satisfy simultaneously your obligations under this
 License and any other pertinent obligations, then as a consequence you may
 not convey it at all.  For example, if you agree to terms that obligate you
 to collect a royalty for further conveying from those to whom you convey
 the Program, the only way you could satisfy both those terms and this
 License would be to refrain entirely from conveying the Program.
  13. Use with the GNU Affero General Public License.
  Notwithstanding any other provision of this License, you have
 permission to link or combine any covered work with a work licensed
 under version 3 of the GNU Affero General Public License into a single
 combined work, and to convey the resulting work.  The terms of this
 License will continue to apply to the part which is the covered work,
 but the special requirements of the GNU Affero General Public License,
 section 13, concerning interaction through a network will apply to the
 combination as such.
  14. Revised Versions of this License.
  The Free Software Foundation may publish revised and/or new versions of
 the GNU General Public License from time to time.  Such new versions will
 be similar in spirit to the present version, but may differ in detail to
 address new problems or concerns.
  Each version is given a distinguishing version number.  If the
 Program specifies that a certain numbered version of the GNU General
 Public License "or any later version" applies to it, you have the
 option of following the terms and conditions either of that numbered
 version or of any later version published by the Free Software
 Foundation.  If the Program does not specify a version number of the
 GNU General Public License, you may choose any version ever published
 by the Free Software Foundation.
  If the Program specifies that a proxy can decide which future
 versions of the GNU General Public License can be used, that proxy's
 public statement of acceptance of a version permanently authorizes you
 to choose that version for the Program.
  Later license versions may give you additional or different
 permissions.  However, no additional obligations are imposed on any
 author or copyright holder as a result of your choosing to follow a
 later version.
  15. Disclaimer of Warranty.
  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
 APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
 HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
 OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
 THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
 IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
 ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
  16. Limitation of Liability.
  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
 THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
 GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
 USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
 DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
 PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
 EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
 SUCH DAMAGES.
  17. Interpretation of Sections 15 and 16.
  If the disclaimer of warranty and limitation of liability provided
 above cannot be given local legal effect according to their terms,
 reviewing courts shall apply local law that most closely approximates
 an absolute waiver of all civil liability in connection with the
 Program, unless a warranty or assumption of liability accompanies a
 copy of the Program in return for a fee.
                     END OF TERMS AND CONDITIONS
            How to Apply These Terms to Your New Programs
  If you develop a new program, and you want it to be of the greatest
 possible use to the public, the best way to achieve this is to make it
 free software which everyone can redistribute and change under these terms.
  To do so, attach the following notices to the program.  It is safest
 to attach them to the start of each source file to most effectively
 state the exclusion of warranty; and each file should have at least
 the "copyright" line and a pointer to where the full notice is found.
    <one line to give the program's name and a brief idea of what it does.>
    Copyright (C) <year>  <name of author>
    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.
    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.
    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <https://www.gnu.org/licenses/>.
 Also add information on how to contact you by electronic and paper mail.
  If the program does terminal interaction, make it output a short
 notice like this when it starts in an interactive mode:
    Debianito Copyright (C) 2026 stornic56
    This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
    This is free software, and you are welcome to redistribute it
    under certain conditions; type `show c' for details.
 The hypothetical commands `show w' and `show c' should show the appropriate
 parts of the General Public License.  Of course, your program's commands
 might be different; for a GUI interface, you would use an "about box".
  You should also get your employer (if you work as a programmer) or school,
 if any, to sign a "copyright disclaimer" for the program, if necessary.
 For more information on this, and how to apply and follow the GNU GPL, see
 <https://www.gnu.org/licenses/>.
  The GNU General Public License does not permit incorporating your program
 into proprietary programs.  If your program is a subroutine library, you
 may consider it more useful to permit linking proprietary applications with
 the library.  If this is what you want to do, use the GNU Lesser General
 Public License instead of this License.  But first, please read
 <https://www.gnu.org/licenses/why-not-lgpl.html>.
@@ -2,7 +2,7 @@
 <div align="center">
-Debianito is a user-friendly post-installation automation script for Debian 11 (Bullseye), Debian 12 (Bookworm) and Debian 13 (Trixie). It streamlines system configuration, driver installation (including NVIDIA drivers), repository setup with backports support, gaming tools integration, and more with an interactive menu-driven interface.
+Debianito is a post-installation automation script for Debian 11 (Bullseye), Debian 12 (Bookworm) and Debian 13 (Trixie). An interactive menu guides system configuration, driver installation (including NVIDIA drivers), repository setup with backports support and gaming tools.
 [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-red.svg?style=for-the-badge&logo=gnu&logoColor=white)](https://github.com/stornic56/debianito-post-install/blob/main/LICENSE)
 ![Script](media/gift/script.gif)
@@ -36,13 +36,37 @@ chmod +x debianito.sh && ./debianito.sh
 ---
 ## Command-Line Usage
 Running `./debianito.sh` with no arguments starts the interactive menu. Three flags change that behavior:
 | Flag | Effect |
 | ---- | ------ |
 | `--yes` | Auto-confirms prompts (unattended mode). Menus still display and still require interaction. |
 | `--allow-destructive` | Allows destructive operations, such as branch migration, without the extra safety gate. |
 | `--help`, `-h` | Show usage and exit. |
 `--yes` alone still blocks branch migration, which is the one operation that can leave the system unbootable. When that happens the script stops and prints `Branch migration is destructive. Re-run with --allow-destructive, or drop --yes to confirm interactively.` to stderr. Combine both flags to run everything unattended:
 ```bash
 ./debianito.sh --yes --allow-destructive
 ```
 An unknown option exits with status 2. For boot profiling, set `DEBIANITO_PROFILE=1` to stamp each boot step to stderr with a timestamp:
 ```bash
 DEBIANITO_PROFILE=1 ./debianito.sh
 ```
 ---
 ## Usage
 After running the script:
 1. **Select Option:** Use arrow keys or type 1-14.
 2. **Navigation:** Use Arrow Keys (Up↑/Down↓) to move between list options and ENTER key to confirm selection.
-3. **Confirm Actions:** Installation prompts use whiptail for TUI confirmations.
+3. **Confirm Actions:** Installation prompts use whiptail for TUI confirmations. Before a batch of packages is applied, the script shows what it is about to install (up to 15 package names plus a count of the rest) and asks you to proceed.
 4. **Review System Info:** Header displays detected Debian version and hardware summary before each action.
 5. **Repeat as Needed:** Return to main menu at any time or exit when done.
@@ -60,12 +84,12 @@ After running the script:
 | **10** | [Swap Management](/docs/swap.md) | Manage swap file or partition size and enable/disable swap space for system stability |
 | **11** | Install Programs and Software | Browse and install packages by category (Development, Themes, System Tools, etc.) using APT |
 | **12** | [Boot Rescue + GRUB](/docs/boot.md) | Config and fix GRUB bootloader issues, chroot repair, or restore system boot configuration |
-| **13** | [Desktop & Display](/docs/desktops_display.md) | Install and configure desktops (XFCE, LXDE) and display managers (LightDM, GDM3, SDDM, greetd) |
+| **13** | [Desktop & Display](/docs/desktops_display.md) | Install and configure desktops (XFCE, LXDE, GNOME, KDE Plasma) and display managers (LightDM, GDM3, SDDM, greetd) |
 | **14** | Exit | Return to terminal |
 ### Install Programs and Software (Option 11)
-The submenu offers the next categories:
+The submenu offers these categories:
 | Option | Category Title | Description |
 | -------- | ------------------------------- | ------------- |
@@ -73,7 +97,7 @@ The submenu offers the next categories:
 | **1** | Customization System | Desktop themes, icon themes, cursor themes, and fonts |
 | **2** | Download & Network | Downloaders (aria2, ytdlp, FileZilla) + Torrent clients (qBittorrent, Deluge, Transmission) |
 | **3** | Internet (Browsers, Email Clients, VPN) | Web browsers (Firefox, LibreWolf, Floorp, Chromium, Tor), email client (Thunderbird), and VPN tools (RiseUp, Proton, Mullvad) |
-| **4** | Communication | Signal, Telegram, HexChat — chat and messaging clients (GUI only) |
+| **4** | Communication | Signal, Telegram, HexChat: chat and messaging clients (GUI only) |
 | **5** | Media Players | Multimedia playback with VLC media player and MPV for advanced video/audio support |
 | **6** | Multimedia & Design | Image editing (GIMP), video editing (Kdenlive, HandBrake), 3D modeling (Blender), audio recording (Audacity), and graphics design (Inkscape) |
 | **7** | Code Editors & IDEs | vim, vim-gtk3, Neovim, Helix, nano, Emacs, Kate, Mousepad, Gedit, Geany, GNOME Text Editor, and VSCodium (VS Code open-source) |
@@ -89,14 +113,14 @@ The submenu offers the next categories:
 ## Quick Start Guide
-For a streamlined post-installation setup (~15-20 minutes), refer to the [Quick Start Visual Guide](/docs/quickstart.md). It provides:
+For a full setup in ~15-20 minutes, refer to the [Quick Start Visual Guide](/docs/quickstart.md). It provides:
 - Step-by-step recommended order for running Debianito options (Steps 1–13)
 - What each option does and when to enable it
 - Screenshots of key dialogs (whiptail menus, confirmations, hardware detection)
 - Troubleshooting tips for common issues (WiFi after firmware install, NVIDIA + Wayland, GRUB boot menu hidden, etc.)
-**Tip:** If you're unsure where to start, follow Steps 1–5 from the Quick Start guide. They cover the essentials: system info, permissions, repositories, firmware, and graphics drivers.
+**Tip:** If you're unsure where to start, follow Steps 1–6 from the Quick Start guide. They cover the essentials: system info, permissions, repositories, firmware, and graphics drivers.
 ---
 ## File Structure
@@ -111,9 +135,17 @@ For a streamlined post-installation setup (~15-20 minutes), refer to the [Quick
 | `modules/extras/` | Software installer sub-modules split by category (themes, downloaders, internet, dev tools, etc.). |
 | `modules/gaming/` | Gaming launcher and optimization scripts: Steam, Heroic, Lutris, performance tools. |
 | `modules/gpu/` | GPU driver installation scripts for AMD and NVIDIA with architecture detection. |
 | `modules/desktops/` | Desktop environment installers: `desktop_xfce.sh`, `desktop_lxde.sh`, `desktop_gnome.sh`, `desktop_kde.sh`. |
 | `modules/hw_detect.sh` | Shared hardware detection (PCI/USB network, WiFi and Bluetooth devices); sourced early by `debianito.sh` and consumed by firmware and Bluetooth modules. |
 | `modules/repos/` | Repository management scripts: migration tool (`migrate.sh`) and format detection (`repo_detect.sh`). |
 | `tests/` | Offline BATS suite: `utils.bats`, `repo_detect.bats`, `desktops.bats` plus shared setup in `test_helper.bash`. |
 | `.github/workflows/ci.yml` | CI pipeline: ShellCheck at warning severity and the BATS suite. |
 ```bash
 ├── .github
 │   └── workflows
 │       └── ci.yml
 ├── .gitignore
 ├── debianito.sh
 ├── docs
 │   ├── boot.md
@@ -156,8 +188,13 @@ For a streamlined post-installation setup (~15-20 minutes), refer to the [Quick
 │   │   ├── extras.sh
 │   │   ├── legacy.sh
 │   │   └── repos.sh
-│   ├── desktop_display.sh
+│   ├── desktop_display.sh
-│   ├── extras
+│   ├── desktops
 │   │   ├── desktop_gnome.sh
 │   │   ├── desktop_kde.sh
 │   │   ├── desktop_lxde.sh
 │   │   └── desktop_xfce.sh
 │   ├── extras
 │   │   ├── audio
 │   │   ├── communication
 │   │   │   └── communication.sh
@@ -212,8 +249,9 @@ For a streamlined post-installation setup (~15-20 minutes), refer to the [Quick
 │   │   ├── _helpers.sh
 │   │   ├── nvidia_manage.sh
 │   │   └── nvidia.sh
-│   ├── gpu.sh
+│   ├── gpu.sh
-│   ├── kernel.sh
+│   ├── hw_detect.sh
 │   ├── kernel.sh
 │   ├── repos
 │   │   ├── migrate.sh
 │   │   └── repo_detect.sh
@@ -225,8 +263,13 @@ For a streamlined post-installation setup (~15-20 minutes), refer to the [Quick
 │   ├── system
 │   │   ├── audio.sh
 │   │   └── system_prefs.sh
-│   ├── utils.sh
+│   ├── utils.sh
-│   └── zram.sh
+│   └── zram.sh
 ├── tests
 │   ├── desktops.bats
 │   ├── repo_detect.bats
 │   ├── test_helper.bash
 │   └── utils.bats
 └── README.md
 ```
@@ -1,331 +0,0 @@
 # Debianito — Quick Start Visual Guide
 > **Scope:** Fresh Debian 11 / 12 / 13 installation → fully configured desktop in ~15-20 minutes.
 > **Prerequisites:** Normal user with `sudo` access. Do **not** run the script as root.
 > **Related:** [README Overview](../README.md) · [System Info](system_info.md) · [Repositories](repos_config.md) · [Firmware](firmware.md) · [GPU](gpu.md) · [Kernel](kernel.md) · [Gaming](gaming.md)
 ---
 ## Before You Start
 ```bash
 git clone https://github.com/stornic56/debianito-post-install
 cd debianito-post-install
 chmod +x debianito.sh && ./debianito.sh
 ```
 The script automatically checks for `whiptail` and `lsb-release`, installs them if missing, verifies `sudo` access, checks network connectivity, and synchronizes the system clock (`systemd-timesyncd` + `tzdata`).
 > **Screenshot placeholder:** `media/screenshots/00-main-menu.png` — Main menu (14 options, whiptail centered at 78×20).
 ---
 ## Recommended Order
 Each step builds on the previous one. Steps 1-5 + 10 are the essential path; 6-9 are optional.
 ### Step 1 — Know Your System
 **Menu:** `1  System Information`
 Opens a whiptail message box populated by `utils.sh` detection functions (`detect_cpu_ram`, `detect_gpu`, `detect_network`, `detect_storage`, `detect_displayserver`, `detect_desktop_environment`).
 You will see:
 - Debian version and codename
 - CPU model and RAM size
 - GPU vendor(s) and device IDs (e.g., `10de:2684` for NVIDIA)
 - Network adapters (Ethernet + WiFi chipset) and their state/IP
 - Storage topology (NVMe / SSD / HDD / USB-SD)
 - Display server (Wayland / X11 / tty) and desktop environment
 Write down the **GPU line** (Intel / AMD / NVIDIA) and any **WiFi chipset** — you will need them in Steps 4-5.
 > **Screenshot placeholder:** `media/screenshots/01-system-info.png` — System Information dialog with hardware summary.
 > **Tip:** If `GPU: No GPU detected` appears, you are on a VM or headless server — skip Step 5 (Graphics Drivers).
 ### Step 2 — Fix Permissions Early (Optional but Recommended)
 **Menu:** `2  User Privileges & Feedback`
 A sub-menu with four toggles:
 | Option | What It Does | When to Enable |
 | -------- | -------------- | ---------------- |
 | Sudo group membership | `usermod -aG sudo $USER` | Fresh install where the first user is not in `sudo` |
 | Passwordless sudo | Creates `/etc/sudoers.d/$USER-nopasswd` with `NOPASSWD` for `apt`, `systemctl`, etc. | Lab / personal machine; skip on shared systems |
 | Repair home ownership | `chown -R $USER:$USER $HOME` | Home files owned by root after a mishandled `sudo` |
 | Sudo password feedback | Writes `Defaults pwfeedback` to `/etc/sudoers.d/pwfeedback` — shows `****` while typing | **Enable now** to avoid typos during the many installs that follow |
 > **Screenshot placeholder:** `media/screenshots/02-user-privileges.png` — User Privileges & Feedback menu.
 > **Screenshot placeholder:** `media/screenshots/02b-pwfeedback.png` — Confirmation dialog for "Sudo Password Feedback" with asterisk preview.
 ### Step 3 — System Preferences (Optional)
 **Menu:** `3  System Preferences`
 ```
 1  Date, Time & Timezone
 2  Language, Locales & Keyboard
 3  Audio & Sound Stack
 4  Back to main menu
 ```
 - **Date, Time & Timezone** — Runs `dpkg-reconfigure tzdata` and then `_ensure_time_synced` (NTP + `systemd-timesyncd`). Fix timezone before `apt update` — a wrong clock breaks GPG verification.
 - **Language, Locales & Keyboard** — Runs `dpkg-reconfigure locales` and `keyboard-configuration`. Requires re-login to apply `LANG`.
 - **Audio & Sound Stack** — Checklist with `pipewire-audio` (or `pipewire` on Bullseye), `alsa-utils`, `pavucontrol` (hidden on TTY), `pulsemixer`, `playerctl`. PipeWire on Trixie offers a Backports vs Stable choice and installs Bluetooth Hi-Res codecs (`LDAC`, `aptX`, `AAC`). See [system_prefs.md](system_prefs.md).
 > **Screenshot placeholder:** `media/screenshots/03-system-prefs.png` — System Preferences menu.
 > **Screenshot placeholder:** `media/screenshots/03b-audio.png` — Audio & Sound checklist with PipeWire selected.
 ### Step 4 — Configure Repositories (Required)
 **Menu:** `4  Configure Repositories`
 ```
 1  Enable Contrib & Non-Free Components
 2  Migrate traditional sources.list to DEB822 format
 3  Setup/Update Backports repositories
 4  [ADVANCED] Upgrade system branch (Testing / SID)
 5  Back to main menu
 ```
 1. Choose **1. Enable Contrib & Non-Free** — adds `contrib`, `non-free`, `non-free-firmware` (Bookworm/Trixie). Required for firmware, NVIDIA drivers, and Steam (`contrib`). The script handles both `/etc/apt/sources.list` (classic) and `/etc/apt/sources.list.d/debian.sources` (DEB822) and validates via `apt update` with automatic rollback.
 2. Choose **3. Setup/Update Backports** — answers `Yes` to enable `trixie-backports` / `bookworm-backports` in a separate file (`debian-backports.sources` or `.list`). Backports gives newer kernels, Mesa, and firmware. See [repos_config.md](repos_config.md).
 > ⚠️ Without `non-free` and `contrib`, Steps 5 and 8 will fail. Do not skip.
 > **Screenshot placeholder:** `media/screenshots/04-repos.png` — Repositories menu.
 > **Screenshot placeholder:** `media/screenshots/04b-backports.png` — Backports confirmation dialog.
 ### Step 5 — Install Firmware & Wireless Drivers
 **Menu:** `5  Firmware, Wireless & Bluetooth`
 The script:
 - Scans **all** network hardware (PCI `lspci -nn` + USB `lsusb`, filtered for Realtek/Intel/Mediatek/Atheros/Qualcomm) and Bluetooth controllers
 - Maps vendors to packages: `firmware-iwlwifi`, `firmware-realtek`, `firmware-mediatek`, `firmware-atheros`, `firmware-intel-misc` — plus `firmware-linux-nonfree` as the base meta-package
 - Builds a plan showing detected controllers and planned packages, including Bluetooth handling (KDE → `bluedevil`, XFCE → `blueman`, GNOME → built-in, plus `pipewire-pulse`/`wireplumber` if PipeWire is active)
 - Asks for confirmation before installing; offers Stable vs Backports for the base firmware
 Accept the plan it shows — it is based on your actual hardware. Broadcom wireless (if present) is handled via `broadcom-sta-dkms` with DKMS build checks and `update-initramfs` + `modprobe wl`.
 > ⚠️ You need internet for this step. If WiFi does not work after firmware install, **reboot** first — the driver needs a fresh load.
 > **Screenshot placeholder:** `media/screenshots/05-firmware-plan.png` — Firmware plan dialog with hardware + package list.
 > **Screenshot placeholder:** `media/screenshots/05b-bluetooth.png` — Bluetooth section of the plan (if applicable).
 ### Step 6 — Install Graphics Drivers
 **Menu:** `6  Graphics Drivers & Mesa Stack`
 Whiptail radiolist with two options:
 ```
 1  Radeon/Intel Mesa
 2  NVIDIA Drivers
 ```
 #### Path A — Radeon/Intel Mesa
 Shows a plan with detected GPUs (`Intel firmware + intel-media-va-driver-non-free` or `i965-va-driver-shaders` for Gen7-, `firmware-amd-graphics` for AMD, plus `Mesa Vulkan/OpenGL/VA-API`). Offers legacy AMD GCN 1.0/1.1 migration to `amdgpu` via GRUB params (`radeon.si_support=0 ... amdgpu.si_support=1`). Installs Mesa from Backports or Stable (`_install_mesa_backports`), verifies `mesa-vulkan-drivers`, and offers vendor-specific telemetry (`radeontop`, `intel-gpu-tools`, `vainfo`).
 #### Path B — NVIDIA Drivers
 Shows detected NVIDIA GPUs and a two-stage menu:
 1. **Manage menu** (if a driver is already installed): *Install / Change Driver Version* vs *Remove Driver and Restore Nouveau*.
 2. **Version menu** (depends on Debian version):
   - Bookworm: `v535` (Recommended) or `v470` (Kepler legacy via `nvidia-tesla-470-driver`)
   - Trixie: `v550` (Debian stable, Recommended), `v590` or `v595` (NVIDIA CUDA Repo with `cuda-keyring` + `nvidia-open` + `firmware-nvidia-gsp`)
 The script auto-detects the GPU architecture (`kepler` / `fermi` / `maxwell` / `pascal` / `turing` / `ampere` / `ada` / `blackwell`) and enforces compatibility — e.g., Blackwell requires `v590+` on Trixie, Maxwell/Pascal on Trixie + backports kernel is forced to `v550` stable, Fermi is vetoed on Bookworm/Trixie with an explanatory message.
 > **Screenshot placeholder:** `media/screenshots/06-gpu-choice.png` — GPU type selector (Radeon/Intel vs NVIDIA).
 > **Screenshot placeholder:** `media/screenshots/06b-nvidia-version.png` — NVIDIA version menu (535 / 470 or 550 / 590 / 595).
 > **Tip:** After installation, **reboot** before testing. NVIDIA drivers need a fresh kernel load.
 ### Step 7 — Kernel Configuration (Optional)
 **Menu:** `7  Kernel`
 ```
 stable     Install linux-image-amd64 (Stable)
 backports  Install from backports (Trixie only)
 rt         Install linux-image-rt-amd64 (Preempt-RT)
 cloud      Install linux-image-cloud-amd64
 back       Return to main menu
 ```
 - **Stable** — default Debian kernel (6.12 LTS on Trixie).
 - **Backports** — only on Trixie; requires `trixie-backports` enabled in Step 4. Newer kernel (e.g., 7.x) for Intel Arrow Lake / AMD Zen 5, Battlemage D3cold, etc.
 - **RT** — Preempt-RT low-latency kernel. Warns if `GPU_TYPE == nvidia` (proprietary drivers may not support RT).
 - **Cloud** — minimal kernel for VMs/containers (`linux-image-cloud-amd64`).
 Each variant installs the matching `linux-headers-*` package atomically (`sudo apt install -y [-t trixie-backports] linux-image-* linux-headers-*`). The script warns about DKMS recompilation if NVIDIA is present.
 > **Screenshot placeholder:** `media/screenshots/07-kernel.png` — Kernel menu with four variants.
 > See [kernel.md](kernel.md) for backports rationale and bootloader details.
 ### Step 8 — Gaming Setup (Optional)
 **Menu:** `8  Gaming Setup`
 A single checklist with all options:
 ```
 [*] i386      Enable 32-bit (i386) architecture
 [*] steam     Steam (requires 32-bit support)
 [*] mangohud  Performance overlay (Vulkan/OpenGL)
 [ ] gamemode  Game performance optimization
 [*] goverlay  MangoHud config GUI
 [ ] heroic    Heroic Launcher (Epic/GOG)
 [ ] java      Minecraft Java Runtime
 [ ] openrgb   OpenRGB (RGB lighting control)
 [ ] lutris    Lutris + Wine (requires 32-bit support)
 [ ] retroarch RetroArch Emulator Frontend
 ```
 - If `steam`, `lutris`, or `i386` is checked, the script runs `dpkg --add-architecture i386` + `apt update`, then installs 32-bit graphics libraries (`_install_nvidia_32bit` or `_install_mesa_32bit`).
 - `steam` checks `contrib` (`ensure_contrib_repo`) and installs `steam-installer`.
 - `heroic` fetches the latest `.deb` from GitHub releases (`api.github.com`).
 - `openrgb` is Bookworm/Trixie only; handles `i2c-dev`, udev, `i2c` group, and `setcap`.
 - `java` offers Temurin 8 / 17 / 21 / 25 via `extrepo adoptium`.
 - Requires GUI for some installers (skipped on headless).
 > **Screenshot placeholder:** `media/screenshots/08-gaming.png` — Gaming checklist with i386 + Steam + MangoHud checked.
 > See [gaming.md](gaming.md) and [retroarch.md](retroarch.md).
 ### Step 9 — ZRAM Compressed Swap (Optional)
 **Menu:** `9  ZRAM`
 ```
 1  View ZRAM status
 2  Create / Reconfigure ZRAM
 3  Remove ZRAM
 4  Back to main menu
 ```
 - **View** — Shows `/etc/default/zramswap` (`ALGO`, `SIZE`, `PRIORITY`) and `zramctl` output.
 - **Create / Reconfigure** — Choice of `lz4` (fastest, gaming) vs `zstd` (better ratio). Recommended size is 50% of RAM (≤8 GB) or 4096 MB fixed (>8 GB), configurable. Writes to `/etc/default/zramswap` (`ALGO`, `SIZE`, `PRIORITY=100`) and `systemctl restart zramswap || true`. Priority 100 ensures ZRAM is used before any disk swap (priority 10).
 - **Remove** — `systemctl stop zramswap`, `swapoff /dev/zram0`, `modprobe -r zram`, `apt purge zram-tools`, removes `/etc/default/zramswap`.
 > **Screenshot placeholder:** `media/screenshots/09-zram-algo.png` — Algorithm choice (lz4 vs zstd).
 > **Screenshot placeholder:** `media/screenshots/09b-zram-status.png` — `zramctl` status output in whiptail.
 > See [zram.md](zram.md).
 ### Step 10 — Swap Management (Optional)
 **Menu:** `10  Swap Management`
 ```
 1  Show current swap & swappiness
 2  Create / resize swapfile
 3  Remove swapfile
 4  Change swappiness
 5  Back to main menu
 ```
 - Uses `/swapfile` with `pri=10` (below ZRAM's 100) and tag `# debianito-managed-swap` in `/etc/fstab`.
 - Btrfs: warns about `nodatacow` (`chattr +C`) and hibernation limitations; uses `dd` instead of `fallocate`.
 - Fstab is written via a temp file and validated with `findmnt --verify` before replacing `/etc/fstab`.
 - Concurrency is guarded by `flock /run/lock/debianito-swap.lock`.
 > **Screenshot placeholder:** `media/screenshots/10-swap.png` — Swap Management menu.
 > See [swap.md](swap.md).
 ### Step 11 — Essential Software
 **Menu:** `11  Install Programs and Software` → `0  Essential Pack`
 One-click install of `htop`, `inxi`, `neofetch`/`fastfetch`, `vlc`, `ufw`, `zip`, `unrar`, `p7zip`, plus `lsb-release` fixes.
 After this, browse the other categories as needed:
 | Category | Example Packages |
 | ---------- | ------------------ |
 | Customization System | Desktop themes, icons, cursors, fonts |
 | Download & Network | aria2, ytdlp, qBittorrent, Deluge |
 | Internet | Firefox, LibreWolf, Chromium, Tor, Thunderbird, RiseUp/Mullvad VPN |
 | Communication | Signal, Telegram, HexChat |
 | Media Players | VLC, MPV |
 | Multimedia & Design | GIMP, Kdenlive, Blender, Audacity, Inkscape |
 | Code Editors & IDEs | Neovim, Helix, Emacs, VSCodium, Geany |
 | Servers & Dev Tools | Nginx, PostgreSQL, Docker, Temurin JDK, Jellyfin |
 | Security & Networking | Wireshark, ClamAV, UFW, fail2ban |
 | Software Center & Flatpak | GNOME Software, KDE Discover, Flatpak |
 | Office & Productivity | LibreOffice, document tools |
 | System Tools | htop/btop, Timeshift, extension-manager, virt-manager |
 | Fetch / System Info | fastfetch, neofetch, hyfetch, screenfetch |
 > **Screenshot placeholder:** `media/screenshots/11-essentials.png` — Category menu with 0-14 options.
 > **Screenshot placeholder:** `media/screenshots/11b-essential-pack.png` — Essential Pack confirmation.
 ### Step 12 — Boot Rescue
 **Menu:** `12  Boot Rescue + GRUB`
 - **GRUB boot menu settings** — 4 presets (hidden 0s / 3s / 5s / custom) writing `GRUB_TIMEOUT`, `GRUB_TIMEOUT_STYLE`, `GRUB_RECORDFAIL_TIMEOUT`, `GRUB_DISABLE_OS_PROBER` to `/etc/default/grub.d/99_script_override.cfg` with `update-grub` + backup/rollback.
 - **UEFI Secure Boot repair** — reinstalls `shim-signed`, `grub-efi-amd64-signed`, `linux-image-amd64`, runs `grub-install` + `update-grub` (UEFI only, checked via `/sys/firmware/efi` + `mokutil`).
 - **Initramfs regeneration** — `update-initramfs -u -k all || true`.
 > See [boot.md](boot.md).
 ### Step 13 — Desktop & Display
 **Menu:** `13  Desktop & Display`
 ```
 1  Desktop Environment
 2  Display Manager
 3  Back to main menu
 ```
 - **Desktop Environment** — XFCE (full / minimal / Wayland `labwc` on Trixie / custom checklist) or LXDE (full / core). Installs polkit rules (`85-suspend.rules`, `89-backlight.rules`) + `backlight` group.
 - **Display Manager** — LightDM (GTK greeter, user list, autologin), GDM3 (user list, autologin, NVIDIA Wayland override via `61-gdm.rules → /dev/null`), SDDM (autologin with session auto-detection `plasmawayland → lxqt-wayland → plasma → lxqt`), greetd (base / tuigreet / gtkgreet / nwg-hello / wlgreet — manual `/etc/greetd/config.toml` required).
 > See [desktops_display.md](desktops_display.md).
 ---
 ## After the Script
 1. **Reboot** if you installed firmware, GPU drivers, or a new kernel.
 2. Verify:
   ```bash
   sudo zramctl              # ZRAM active?
   sudo swapon --show        # Swap with correct priorities?
   vainfo                    # VA-API acceleration?
   nvidia-smi                # NVIDIA driver loaded?
   systemctl status bluetooth # Bluetooth active?
   ```
 3. For gaming, enable `i386` was handled — verify with `dpkg --print-foreign-architectures | grep i386`.
 ---
 ## Troubleshooting Quick Answers
 | Symptom | Fix |
 | --------- | ----- |
 | **WiFi not working after firmware** | Reboot. Check `lspci -nn \| grep Network` and verify the package (`firmware-iwlwifi` etc.) is `ii` via `dpkg -l`. Ensure `non-free` + `non-free-firmware` were enabled in Step 4. |
 | **Black screen after NVIDIA + Wayland (GNOME/GDM3)** | At login, select *GNOME on Xorg* (gear icon) or disable Wayland: `sudo nano /etc/gdm3/daemon.conf` → `WaylandEnable=false`. The script only warns about Debian bug #1109409, it does not force X11. |
 | **GRUB menu hidden and cannot enter** | Hold `ESC` immediately after power-on. Or boot a live USB, `chroot`, and run `12  Boot Rescue → GRUB boot menu settings → Show 5 seconds`. |
 | **Steam fails to start** | Verify `i386` is enabled: `dpkg --print-foreign-architectures`. Check `contrib` is in `/etc/apt/sources.list`. Re-run `8  Gaming Setup` and ensure the checklist had `i386` + `steam` checked. |
 | **greetd installed but cannot log in** | This is expected — you must create `/etc/greetd/config.toml` manually. See `man greetd` and `man 5 greetd-sessions`. |
 | **Bluetooth tray icon missing** | Reboot or `systemctl restart bluetooth`. Ensure `bluez`, `bluedevil` (KDE) or `blueman` (XFCE) is installed. For PipeWire, check `systemctl --user status pipewire pipewire-pulse wireplumber`. |
 | **PipeWire crackling / no Bluetooth Hi-Res codec** | Re-run `3  System Preferences → Audio & Sound → PipeWire Audio Stack`. Verify `libldacbt-*`, `libopenaptx0`, `libfdk-aac2t64` are installed (`dpkg -l \| grep -E 'ldac\|aptx\|fdk'`). |
 ---
 ## Taking Screenshots for This Guide
 Screenshots are taken from `whiptail` dialogs. To capture them:
 1. Run the script inside a terminal that supports image export (e.g., `gnome-terminal` + `gnome-screenshot`, or `asciinema`).
 2. For whiptail, press `PrintScreen` or use `import -window root screenshot.png` (ImageMagick).
 3. Save under `media/screenshots/` with the filenames referenced above (`01-system-info.png`, `04-repos.png`, etc.).
 4. Keep width ≈ 800px; the script uses fixed `TUI_ANCHO=78` and `TUI_ALTO=20` centered dialogs.
 > **Note:** Until real screenshots are added, the placeholders above describe the expected content of each image.
@@ -2,11 +2,11 @@
 ### 1. What does this component do?
-This component serves as a comprehensive rescue toolkit designed to diagnose and fix boot-related issues on Debian systems, specifically targeting GRUB configuration, UEFI Secure Boot integrity, and initrd image validity. It provides three primary operations: configuring the GRUB boot menu behavior (including timeout adjustments and visibility settings), repairing UEFI Secure Boot by reinstalling signed bootloader packages after kernel or driver changes, and regenerating initramfs images to resolve missing driver errors. All modifications are protected by automatic backup creation before system files are altered, with built-in rollback mechanisms that restore the original state if any operation fails during execution.
+This component diagnoses and fixes boot-related problems on Debian: GRUB configuration, UEFI Secure Boot integrity and initrd image validity. It performs three operations: configuring the GRUB boot menu (timeout and visibility settings), repairing UEFI Secure Boot by reinstalling signed bootloader packages after kernel or driver changes, and regenerating initramfs images to fix missing driver errors. Every modification starts with a timestamped backup, and a failed operation rolls back to the original state.
 ### 2. Logical Execution Flow
-**Block 1 — GRUB Boot Menu Settings**
+**Block 1: GRUB Boot Menu Settings**
 - **Menu Options:** Users select from four presets or a custom option to control boot behavior:
    1. Hide GRUB menu entirely (Fastest boot, requires holding ESC during power-on).
@@ -17,7 +17,7 @@ This component serves as a comprehensive rescue toolkit designed to diagnose and
 - **Backup & Safety:** Before applying changes, the script creates a timestamped backup of `/etc/default/grub`. It writes an override configuration file at `/etc/default/grub.d/99_script_override.cfg` to ensure settings persist across updates.
 - **Execution & Rollback:** The system runs `update-grub` to apply changes. If this command fails, the script automatically restores the timestamped backup and removes the override file to prevent boot issues.
-**Block 2 — UEFI Secure Boot Repair**
+**Block 2: UEFI Secure Boot Repair**
 - **Pre-checks:** Before proceeding, the script verifies two conditions:
    1. The system is running in UEFI mode (checks for existence of `/sys/firmware/efi`).
@@ -28,15 +28,15 @@ This component serves as a comprehensive rescue toolkit designed to diagnose and
    2. Reinstalls GRUB to the EFI partition using `grub-install` with the appropriate target and directory detection (preferring `/boot/efi` over `/boot`).
    3. Regenerates the GRUB configuration via `update-grub`.
-**Block 3 — Initramfs Regeneration**
+**Block 3: Initramfs Regeneration**
 - **Confirmation:** The script prompts for user confirmation before proceeding to avoid unintended rebuilds.
 - **Execution:** Upon approval, it runs `update-initramfs -u -k all || true` to regenerate initrd images for all installed kernels.
 - **Purpose:** This fixes boot issues caused by missing drivers or corrupted initrd images that prevent the system from loading properly.
-### 3. Intelligent Automation
+### 3. Safeguards and Automation
- **EFI Directory Detection:** The script intelligently detects the EFI partition, checking `/boot/efi` first and falling back to `/boot` if necessary.
+- **EFI Directory Detection:** The script detects the EFI partition, checking `/boot/efi` first and falling back to `/boot` if necessary.
 - **Secure Boot State Verification:** Instead of assuming Secure Boot is active, it uses `mokutil --sb-state` to verify the actual state before attempting repairs on non-UEFI or disabled systems.
 - **GRUB Backup Strategy:** A timestamped backup file (e.g., `/etc/default/grub.backup.YYYYMMDD_HHMMSS`) is created prior to any modification, ensuring a safe point for rollback.
 - **Rollback Mechanism:** If `update-grub` fails during the GRUB settings or Secure Boot repair process, the script automatically restores the backup and cleans up temporary override files.
@@ -44,7 +44,7 @@ This component serves as a comprehensive rescue toolkit designed to diagnose and
 - **Input Validation:** Custom timeout inputs are validated using regex matching for integers (e.g., `^-?[0-9]+$`), allowing negative numbers like -1 while rejecting invalid text.
 - **Variable Handling Logic:** The `_set_grub_var()` function handles three distinct cases: updating an existing variable, uncommenting a commented variable, or appending a new variable if it does not exist in the configuration file.
-### 4. Paquetes y Recursos Gestionados
+### 4. Managed Packages and Resources
 **Boot Packages Reinstalled (Secure Boot Repair):**
@@ -10,16 +10,16 @@ This component manages both desktop environments and display managers. Desktop E
 The execution logic is divided into five functional blocks:
-**Block 1 — Desktop Environment Selection & Installation**
+**Block 1: Desktop Environment Selection & Installation**
 - The main menu (`manage_desktop_display` in `desktop_display.sh`) offers two primary options: `1  Desktop Environment` and `2  Display Manager` (plus `3  Back to main menu`).
 - **Desktop Environment** opens `desktop_environment_menu` with four environments:
-  1. **XFCE** — full / minimal / Wayland (`labwc`, Debian 13 only) / custom package checklist.
+  1. **XFCE**: full / minimal / Wayland (`labwc`, Debian 13 only) / custom package checklist.
-  2. **LXDE** — full / core.
+  2. **LXDE**: full / core.
-  3. **GNOME** — full (`gnome`) / core (`gnome-core`), with GDM3.
+  3. **GNOME**: full (`gnome`) / core (`gnome-core`), with GDM3.
-  4. **KDE Plasma** — full (`kde-standard`) / minimal (`kde-plasma-desktop`), with SDDM.
+  4. **KDE Plasma**: full (`kde-standard`) / minimal (`kde-plasma-desktop`), with SDDM.
 - Each environment lives in its own module under `modules/desktops/` and is lazy-loaded from the menu dispatch with `_load_module xfce|lxde|gnome|kde` (dependencies: `desktop_display` + `audio`).
- **Display Manager** opens `display_manager_menu` — LightDM, GDM3, SDDM, and greetd (12/13 only).
+- **Display Manager** opens `display_manager_menu`: LightDM, GDM3, SDDM, and greetd (12/13 only).
 - **Available Managers:**
  - LightDM (available on all Debian versions).
  - GDM3 (available on all Debian versions).
@@ -27,7 +27,7 @@ The execution logic is divided into five functional blocks:
  - greetd (available only on Debian 12 and 13).
 - Each selected manager opens its own dedicated configuration submenu.
-**Block 2 — LightDM Configuration**
+**Block 2: LightDM Configuration**
 - A checklist menu presents three options:
  1. Install LightDM + GTK Greeter (auto-selects the display manager via debconf-set-selections).
@@ -35,7 +35,7 @@ The execution logic is divided into five functional blocks:
  3. Enable autologin for current user (uncomments `autologin-user` and sets timeout to 0 in the main config).
 - **Idempotency:** The script checks if `lightdm` and `lightdm-gtk-greeter-settings` are already installed before attempting installation, skipping redundant steps.
-**Block 3 — GDM3 Configuration**
+**Block 3: GDM3 Configuration**
 - A checklist menu presents up to four options:
  1. Install/Reinstall gdm3 (auto-selects via debconf).
@@ -47,7 +47,7 @@ The execution logic is divided into five functional blocks:
     - **Risk Warning:** Displays a warning that this may break graphics or cause instability.
     - **Toggle Behavior:** If the symlink exists, removing it reverts to default behavior; if not present, creating it enables the override.
-**Block 4 — SDDM Configuration**
+**Block 4: SDDM Configuration**
 - A submenu offers two options:
  1. Install SDDM (auto-selects via debconf).
@@ -56,7 +56,7 @@ The execution logic is divided into five functional blocks:
     - **Configuration:** Writes autologin settings to `/etc/sddm.conf.d/autologin.conf`.
     - **Fallback:** If no session is found, it enables autologin but warns that SDDM will use the default session.
-**Block 5 — greetd Configuration**
+**Block 5: greetd Configuration**
 - greetd is a minimal, modern display manager designed for Wayland environments.
 - Submenu options vary by Debian version:
@@ -65,9 +65,9 @@ The execution logic is divided into five functional blocks:
 - **Backports Handling:** On Bookworm, `tuigreet` is installed from backports if not enabled.
 - **Important Warning:** greetd is installed but NOT configured by the script. The user must manually create `/etc/greetd/config.toml` to be able to log in. The script displays a warning with references to man pages for configuration details.
-### 3. Smart Automations
+### 3. Automations
-The component utilizes several intelligent automation features:
+The component automates several steps:
 - **debconf-set-selections:** Pre-selects the display manager as default before `apt install`, preventing the interactive "Configuring shared/default-x-display-manager" dialog that would otherwise pause the script execution.
 - **Session Auto-Detection (SDDM):** Checks `.desktop` files in priority order (Wayland first, then X11) to set the correct session type for autologin configuration.
@@ -1,22 +1,22 @@
 # Option 5: Firmware, Wireless & Bluetooth
-## 1. The Hidden Debian "Problem"
+## 1. What the Debian Package Misses
-In standard Debian packaging, the meta-package `firmware-linux-nonfree` serves as a generic aggregator for hardware blobs. However, due to internal dependency resolution rules and conservative versioning strategies within the repository, this package often fails to automatically include vendor-specific firmware drivers for newer or niche network controllers (specifically Realtek Wi-Fi/Bluetooth and Intel Ethernet/Wi-Fi variants).
+In standard Debian packaging, the meta-package `firmware-linux-nonfree` collects hardware blobs from many sources. Its dependency rules and conservative versioning mean it often misses vendor-specific firmware for newer or niche network controllers (Realtek Wi-Fi/Bluetooth and Intel Ethernet/Wi-Fi variants in particular).
-This script acts as an intelligent injector to bridge that gap. It does not rely solely on the meta-package's `Recommends` field; instead, it actively scans the hardware topology to identify missing dependencies. By decoupling the detection from the installation logic, the architecture ensures that even if the base package is installed, specific vendor blobs (e.g., `firmware-iwlwifi`, `firmware-realtek`) are explicitly pulled in only when their corresponding hardware IDs are confirmed present on the system. This prevents "half-baked" network connectivity where the interface exists but lacks the necessary firmware to initialize.
+This script fills that gap. It scans the hardware itself instead of trusting the meta-package's `Recommends` field: detection is separate from installation, so a specific blob (e.g., `firmware-iwlwifi`, `firmware-realtek`) is pulled in only when its hardware ID is present, even if the base package is already installed. The result is no network interface that appears but cannot initialize because its firmware is missing.
 ## 2. Dual Scan Engine (PCI & USB)
-To ensure comprehensive hardware detection while minimizing false positives, the script utilizes a dual-scan engine that interrogates both PCI and USB buses with strict filtering logic:
+The script scans both the PCI and USB buses with strict filters, which catches more hardware while keeping false positives low:
-* **PCI Bus Scanning (`lspci`):** The engine parses `lspci -nn` output specifically targeting lines containing "network controller" or "ethernet controller". This captures both wireless adapters (e.g., Intel AX200) and wired NICs (e.g., Realtek RTL8125 2.5GbE), ensuring that Ethernet firmware requirements are also met during the process.
+* **PCI Bus Scanning (`lspci`):** The engine parses `lspci -nn` output specifically targeting lines containing "network controller" or "ethernet controller". This captures both wireless adapters (e.g., Intel AX200) and wired NICs (e.g., Realtek RTL8125 2.5GbE), so Ethernet firmware needs are covered too.
 * **USB Bus Scanning (`lsusb`):** The USB scan applies keyword filtering to ignore peripherals unrelated to networking, such as audio devices or card readers. It specifically looks for terms like "wireless", "wifi", "802.11", and "wlan". Bluetooth devices are also detected separately through `PCI_BT_DEVS` and `USB_BT_DEVS`.
-* **Deduplication:** The collected device lists are merged into a single array (`dev_list`) to prevent duplicate processing of the same hardware instance across different bus categories, ensuring a clean plan generation.
+* **Deduplication:** The collected device lists are merged into a single array (`dev_list`) so the same hardware is not processed twice across bus categories and the plan stays clean.
 ## 3. Dynamic Hardware Mapping Matrix
-The script employs an associative mapping strategy in `_detect_firmware_needs` to translate raw vendor strings from `lspci`/`lsusb` into specific Debian package names. This matrix is critical for handling the "Intel Split" and other vendor-specific requirements:
+The script employs an associative mapping strategy in `_detect_firmware_needs` to translate raw vendor strings from `lspci`/`lsusb` into specific Debian package names. This mapping handles the "Intel Split" and other vendor-specific requirements:
 * **Vendor Filtering:** The engine first filters out generic or unsupported vendors (e.g., non-Realtek, non-Intel, non-Atheros) to avoid unnecessary package pulls.
 * **Package Assignment Logic:**
@@ -26,26 +26,26 @@ The script employs an associative mapping strategy in `_detect_firmware_needs` t
  * **MediaTek / Ralink Hardware** ➔ `firmware-mediatek`.
  * **Atheros / Qualcomm Hardware** ➔ `firmware-atheros`.
-This mapping ensures that if a system contains an Intel Wi-Fi 6 card, the script explicitly queues `firmware-iwlwifi` regardless of whether the base meta-package claims to cover it. The output is rendered as a deduplicated plan with visual indicators (e.g., `[+] package ← hardware`) for user clarity.
+So a system with an Intel Wi-Fi 6 card gets `firmware-iwlwifi` queued explicitly, whether or not the base meta-package claims to cover it. The output is rendered as a deduplicated plan with visual indicators (e.g., `[+] package ← hardware`) for user clarity.
 ## 4. Installation Execution Flow (Atomic Pipeline)
-The installation process follows a strict atomic pipeline defined in `install_firmware`, ensuring system stability and version consistency:
+The installation runs through the atomic pipeline in `install_firmware`:
 1. **Repository Validation:** The script first verifies that `/etc/apt/sources.list` or `.d/` contains the `non-free` component. If absent, it halts to prevent installation failures.
 2. **Plan Rendering & Confirmation:** A diagnostic tree is generated showing detected controllers and planned packages. The user must explicitly confirm ("Apply the network & firmware plan?") before proceeding.
 3. **Base Meta-Package Selection (Backports vs. Stable):**
    * If `firmware-linux-nonfree` is already installed, the script checks for a newer version in backports (`${DEBIAN_CODENAME}-backports`). It prompts to upgrade if available, as backports often contain firmware for very recent hardware not yet in stable.
-    * If not installed, it presents a choice between Stable (Ultra-tested) and Backports (Recommended for modern hardware).
+    * If not installed, it presents a choice between Stable (thoroughly tested) and Backports (Recommended for modern hardware).
 4. **Sequential Injection:** After the base package is secured, the script iterates through `_DETECTED_FW_PKGS`. It uses `apt-cache policy` to validate availability before installing specific vendor packages (`firmware-realtek`, etc.), skipping those already present or unavailable in repositories.
 ## 5. Broadcom Wireless Support (DKMS Single-Path)
-Broadcom chipsets require proprietary handling because no open-source driver covers most `14e4:*` devices on modern kernels. The current implementation in `firmware.sh:_handle_wireless` uses a **single-path DKMS flow** (`broadcom-sta-dkms` + `wl` module) — not a 3-tier fallback:
+Broadcom chipsets require proprietary handling because no open-source driver covers most `14e4:*` devices on modern kernels. The current implementation in `firmware.sh:_handle_wireless` uses a **single-path DKMS flow** (`broadcom-sta-dkms` + `wl` module) instead of a 3-tier fallback:
-1. **Device detection** — Iterates `PCI_NET_DEVS` (parsed from `lspci -nn` by the on-demand detection battery) and extracts the Broadcom ID `14e4:XXXX`. Non-Broadcom devices are skipped.
+1. **Device detection**: Iterates `PCI_NET_DEVS` (parsed from `lspci -nn` by the on-demand detection battery) and extracts the Broadcom ID `14e4:XXXX`. Non-Broadcom devices are skipped.
-2. **Dependency guard** — Verifies `linux-headers-amd64` and `dkms` are available via `apt-cache show`. If missing, shows: `"linux-headers-amd64 or dkms are not available in your repositories."`
+2. **Dependency guard**: Verifies `linux-headers-amd64` and `dkms` are available via `apt-cache show`. If missing, shows: `"linux-headers-amd64 or dkms are not available in your repositories."`
-3. **User confirmation** — `whiptail --yesno "Install broadcom-sta-dkms, dkms, and wireless-tools?"`
+3. **User confirmation**: `whiptail --yesno "Install broadcom-sta-dkms, dkms, and wireless-tools?"`
 4. **Step-by-step install** (allows partial failure without aborting the whole module):
   ```bash
@@ -53,7 +53,7 @@ Broadcom chipsets require proprietary handling because no open-source driver cov
   _run_cmd "Broadcom Driver" "sudo DEBIAN_FRONTEND=noninteractive apt install -y broadcom-sta-dkms" || true
   ```
-5. **Blacklist persistence** — Writes `/etc/modprobe.d/blacklist-broadcom.conf`:
+5. **Blacklist persistence**: Writes `/etc/modprobe.d/blacklist-broadcom.conf`:
   ```
   blacklist b43
@@ -63,7 +63,7 @@ Broadcom chipsets require proprietary handling because no open-source driver cov
   blacklist ssb
   ```
-6. **SSH Warning + Module Switch** — Before unloading current WiFi modules, the script warns about SSH disconnection. Then removes conflicting modules and loads the Broadcom driver:
+6. **SSH Warning + Module Switch**: Before unloading current WiFi modules, the script warns about SSH disconnection. Then removes conflicting modules and loads the Broadcom driver:
   ```bash
   _msg "Network Warning" "The script is about to unload current WiFi kernel modules to load the Broadcom driver.
@@ -74,30 +74,30 @@ If you are connected via SSH over WiFi, YOUR CONNECTION WILL DROP. Please reconn
   ```
-7. **Initramfs** — Rebuilds the initramfs to include the new `wl` module:
+7. **Initramfs**: Rebuilds the initramfs to include the new `wl` module:
   ```bash
   _run_cmd "Initramfs" "sudo update-initramfs -u" || true
   ```
-1. **Combo BT handling** — If a Broadcom Bluetooth device is also present (`PCI_BT_DEVS` grep `broadcom`), writes `softdep wl post: btusb` to `/etc/modprobe.d/broadcom-combo.conf`
+1. **Combo BT handling**: If a Broadcom Bluetooth device is also present (`PCI_BT_DEVS` grep `broadcom`), writes `softdep wl post: btusb` to `/etc/modprobe.d/broadcom-combo.conf`
-2. **Post-DKMS verification** — Checks for `/lib/modules/$(uname -r)/updates/dkms/wl.ko*`. If missing, shows the last 20 lines of `dmesg` and offers `dpkg-reconfigure broadcom-sta-dkms`. On success, verifies `lsmod | grep ^wl` and reports `Broadcom WiFi activated (wl module loaded)` or `driver installed but wl module did not load — reboot required`.
+2. **Post-DKMS verification**: Checks for `/lib/modules/$(uname -r)/updates/dkms/wl.ko*`. If missing, shows the last 20 lines of `dmesg` and offers `dpkg-reconfigure broadcom-sta-dkms`. On success, verifies `lsmod | grep ^wl` and reports `Broadcom WiFi activated (wl module loaded)` or `driver installed but wl module did not load — reboot required`.
-USB Broadcom (`0a5c` vendor, `lsusb`) is detected but **not auto-installed** — the script shows a message that Linux lacks native drivers for most USB Broadcom WiFi chips and that `ndiswrapper` may be needed.
+USB Broadcom (`0a5c` vendor, `lsusb`) is detected but **not auto-installed**: the script shows a message that Linux lacks native drivers for most USB Broadcom WiFi chips and that `ndiswrapper` may be needed.
 > **Historical note:** Earlier drafts of this document described a 3-tier system (`firmware-brcm80211` → `firmware-b43-installer` → `broadcom-sta-dkms`). The current script has consolidated to the DKMS path only. The other firmware packages are still available via the base `firmware-linux-nonfree` metapackage and vendor-specific packages (`firmware-realtek`, etc.).
 ## 6. Bluetooth Stack Integration
-Bluetooth support is handled through a dedicated module (`bluetooth.sh`) that integrates seamlessly with the firmware detection process:
+Bluetooth support is handled through a dedicated module (`bluetooth.sh`) that reuses the firmware module's device detection:
-* **Hardware Detection:** The script identifies both PCI and USB Bluetooth controllers using `PCI_BT_DEVS` and `USB_BT_DEVS` arrays, ensuring comprehensive coverage of all Bluetooth hardware types.
+* **Hardware Detection:** The script identifies both PCI and USB Bluetooth controllers via the `PCI_BT_DEVS` and `USB_BT_DEVS` arrays, covering all Bluetooth hardware types.
 * **Base Stack Installation:** When Bluetooth hardware is detected, the system installs the core stack (`bluez`, `bluez-utils`, `bluez-obexd`) if not already present.
 * **Desktop Environment Optimization:** Based on the detected desktop environment:
  * **KDE:** Installs `bluedevil` and optionally `pipewire-pulse` + `wireplumber` for Pipewire audio server integration.
  * **GNOME:** Uses built-in GNOME Bluetooth support in `gnome-control-center`.
  * **XFCE/Other:** Installs `blueman` as the GTK Bluetooth manager.
-* **Service Management:** The script ensures the Bluetooth service is enabled and started automatically on boot, with session restart or reboot recommendation for desktop applets to load properly.
+* **Service Management:** The script enables and starts the Bluetooth service on boot, and recommends a session restart or reboot so desktop applets load properly.
-This modular approach keeps Bluetooth handling separate from network firmware while maintaining tight integration through shared device detection arrays and coordinated installation flow.
+Bluetooth handling stays separate from network firmware; both share the same device detection arrays.
@@ -2,9 +2,9 @@
 ### 1. Philosophy of the Gaming Environment in Debian
-The Debianito gaming module transforms a server-grade Debian installation into a dedicated gaming station by carefully isolating dependencies and configuring compatibility layers without compromising system stability. The core philosophy follows three principles:
+The Debianito gaming module turns a plain Debian installation into a gaming station. It isolates the gaming dependencies from the base system and configures the compatibility layers without putting system stability at risk. The design follows three principles:
-**Dependency Isolation:** All gaming-specific packages (Steam, Heroic, Mesa 32-bit libraries) are installed in user-space where possible, preventing conflicts with base system packages. The `steam-installer` package from Debian's contrib section is used as the bootstrap mechanism rather than Valve's official repository for stability reasons—this ensures compatibility with Debian's package management and reduces update complexity.
+**Dependency Isolation:** All gaming-specific packages (Steam, Heroic, Mesa 32-bit libraries) are installed in user-space where possible, preventing conflicts with base system packages. The `steam-installer` package from Debian's contrib section is used as the bootstrap mechanism rather than Valve's official repository for stability reasons. This ensures compatibility with Debian's package management and reduces update complexity.
 **Compatibility Layer Configuration:** Proton/Wine support is enabled through automatic installation of required 32-bit libraries (`libgl1-mesa-dri:i386`, `mesa-vulkan-drivers:i386`) that are mandatory for running Windows-only games on Linux. The module detects GPU architecture and installs appropriate drivers (NVIDIA proprietary, AMD open-source, Intel built-in) before attempting any launcher installation.
@@ -16,7 +16,7 @@ The module architecture separates concerns into distinct scripts (`steam.sh`, `h
 ### 2. Launchers and Compatibility Layers (Steam & Heroic)
-**Steam Installation Logic:** The `install_steam()` function in `steam.sh` leverages Debian's native package management through the `apt install -y steam-installer` command. This approach differs from Valve's official repository for several reasons:
+**Steam Installation Logic:** The `install_steam()` function in `steam.sh` uses Debian's native package management through the `apt install -y steam-installer` command. This approach differs from Valve's official repository for several reasons:
 1. **32-bit Architecture Requirement:** Steam requires 32-bit libraries to run modern Windows games via Proton. The script explicitly prompts users to enable Multi-Arch support (`dpkg --add-architecture i386`) and install the complete Mesa stack for both amd64 and i386 architectures:
@@ -25,7 +25,7 @@ The module architecture separates concerns into distinct scripts (`steam.sh`, `h
              libgl1-mesa-dri:i386 libegl-mesa0:i386 mesa-va-drivers:i386
   ```
-2. **Runtime Dependency Chain:** The `steam-installer` package depends on several critical components:
+2. **Runtime Dependency Chain:** The `steam-installer` package depends on several components:
   - `debconf` and `cdebconf` for configuration management
   - `default-dbus-session-bus` for inter-process communication
   - `lsof` for file listing utilities
@@ -52,7 +52,7 @@ This approach ensures users always get the latest stable release while maintaini
 ### 3. Optimization Engine and Telemetry (GameMode & MangoHud)
-**Feral GameMode Daemon:** When a game launches with `gamemoderun`, the Feral GameMode daemon performs several critical optimizations at the kernel level:
+**Feral GameMode Daemon:** When a game launches with `gamemoderun`, the Feral GameMode daemon performs several optimizations at the kernel level:
 1. **CPU Scheduler Priority:** Adjusts scheduling policies to prioritize gaming processes over background tasks, reducing latency spikes during gameplay
 2. **I/O Priority Management:** Increases I/O priority for game processes while deprioritizing non-essential system operations (updates, backups)
@@ -83,7 +83,7 @@ if dpkg --print-foreign-architectures | grep -q i386; then
 fi
 ```
-The `goverlay` component extends this functionality by integrating with Wayland compositors for smoother overlay behavior on modern desktop environments. Both tools work together to provide comprehensive performance visibility without requiring game-specific configuration.
+The `goverlay` component extends this functionality by integrating with Wayland compositors for smoother overlay behavior on modern desktop environments. The two tools need no game-specific configuration.
 ---
@@ -121,19 +121,19 @@ This approach eliminates the security risk of running OpenRGB as root while main
 | **Temurin 21** | Latest game engines, cutting-edge mods | Provides best performance for modern Java applications |
 | **Temurin 25** | Minecraft 26+ and latest game engines | Best performance for the newest Java applications |
-**Repository Management via extrepo:** The script leverages the `extrepo` utility to manage external repositories cleanly rather than manually injecting repository URLs into system files. This approach offers several advantages:
+**Repository Management via extrepo:** The script uses the `extrepo` utility to manage external repositories instead of injecting repository URLs into system files by hand. This approach offers several advantages:
 1. **Automated Keyring Handling:** `extrepo` manages GPG keys and source file configurations automatically, eliminating manual intervention with `/etc/apt/sources.list.d/`.
 2. **Dependency Resolution:** The utility checks for its own installation and handles the enabling of the Adoptium Temurin repository before proceeding with package installation.
 3. **Maintenance Safety:** Updates to the upstream repository are reflected through `extrepo` without requiring direct edits to system configuration files, reducing the risk of breakage during OS updates.
-**Version Selection Logic:** Users can choose which Temurin version to install based on their specific game requirements via a TUI menu (`install_minecraft_java()`). The module justifies offering all four versions because:
+**Version Selection Logic:** Users can choose which Temurin version to install based on their specific game requirements via a TUI menu (`install_minecraft_java()`). The module offers all four versions because:
 1. **Backward Compatibility:** Java 8 remains in use by many Minecraft mods and older game clients that haven't been updated for newer JVMs
 2. **Performance Optimization:** Java 21 provides the best performance characteristics for modern games with heavy multithreading requirements
 3. **Security Updates:** All Temurin versions receive regular security patches from the Eclipse Foundation community
-The installation process ensures clean repository management without polluting the system with multiple conflicting JRE installations, maintaining Debian's package integrity while providing flexibility for different gaming scenarios. It automatically installs `extrepo` if not present and enables the Adoptium source before proceeding with version-specific packages (e.g., `temurin-8-jre`, `temurin-17-jre`, `temurin-25-jre`).
+The install avoids multiple conflicting JRE installations. It installs `extrepo` if it is missing, enables the Adoptium source and then installs the chosen packages (e.g., `temurin-8-jre`, `temurin-17-jre`, `temurin-25-jre`).
 ### References
@@ -147,4 +147,4 @@ The installation process ensures clean repository management without polluting t
 - [https://github.com/flightlessmango/Mangohud](https://github.com/flightlessmango/Mangohud)
 - [https://github.com/feralinteractive/gamemode](https://github.com/feralinteractive/gamemode)
 - [https://gitlab.com/CalcProgrammer1/OpenRGB](https://gitlab.com/CalcProgrammer1/OpenRGB)
- [https://adoptium.net/es/installation/linux](https://adoptium.net/es/installation/linux)
+- [https://adoptium.net/en/installation/linux](https://adoptium.net/en/installation/linux)
@@ -2,19 +2,19 @@
 ### 1. Philosophy of the Graphics Stack (Open-Source vs. Proprietary)
-The `debianito` script adopts a **hybrid-first architecture philosophy**. It prioritizes the stability and security of the Linux kernel's native open-source drivers while maintaining the capability to inject proprietary solutions where necessary for performance or legacy support. This approach is implemented through three distinct layers:
+The `debianito` script prefers the open-source drivers that ship with the Linux kernel and injects proprietary ones only where performance or legacy support requires it. The work is split across three layers:
 1. **DRM/KMS & Mesa (Open-Source Core)**: For Intel and AMD hardware, the script relies on the `i915`/`amdgpu` kernel drivers (KMS) paired with the `Mesa` user-space stack. This ensures that graphics acceleration is handled by the mainline Linux kernel without requiring third-party blobs or external repositories for basic functionality. The script explicitly installs the necessary Gallium3D drivers (`radeonsi`, `iris`) and Vulkan implementations (`RADV`).
 2. **Proprietary Injection (NVIDIA)**: For NVIDIA hardware, the open-source Nouveau driver is often insufficient for gaming or compute workloads. The script manages the installation of proprietary `.run` or DKMS modules via official NVIDIA repositories. This requires careful handling to ensure compatibility with the running kernel version, especially when using backports kernels.
-3. **Firmware & Microcode**: A critical prerequisite layer handled by `firmware.sh`. Before any driver can load, the correct firmware blobs (e.g., `iwlwifi`, `amdgpu`, `nvidia`) must be present in `/lib/firmware`. The script scans hardware via `lspci` and `lsusb` to populate a dynamic installation plan for these non-free components.
+3. **Firmware & Microcode**: A prerequisite layer handled by `firmware.sh`. Before any driver can load, the correct firmware blobs (e.g., `iwlwifi`, `amdgpu`, `nvidia`) must be present in `/lib/firmware`. The script scans hardware via `lspci` and `lsusb` to populate a dynamic installation plan for these non-free components.
-This philosophy ensures that users on standard Debian Stable releases get maximum compatibility, while advanced users can opt into backports kernels or enterprise NVIDIA repositories without breaking the base system integrity.
+Users on Debian Stable get compatibility by default, while advanced users can opt into backports kernels or the NVIDIA enterprise repository without breaking the base system.
 ---
 ### 2. The Automatic GPU Detection Pipeline
-The script utilizes a robust pre-flight detection sequence defined in `utils.sh` and executed within `gpu.sh`. This pipeline minimizes user interaction by automatically categorizing hardware before presenting installation options.
+The script runs a pre-flight detection sequence defined in `utils.sh` and executed in `gpu.sh`. It categorizes the hardware before showing installation options, so the user answers fewer questions.
 **Detection Flow:**
@@ -40,7 +40,7 @@ The script utilizes a robust pre-flight detection sequence defined in `utils.sh`
    * Install Intel firmware/drivers first to ensure the base display server works.
    * Install NVIDIA drivers second, configuring them for PRIME offloading if detected.
-This "detect-then-deploy" model prevents users from installing unnecessary drivers (e.g., `i965` on an RTX 4090) and ensures that critical firmware is present before the driver installation phase begins.
+This detect-then-deploy order keeps users from installing unnecessary drivers (e.g., `i965` on an RTX 4090) and puts the firmware in place before drivers are installed.
 ---
@@ -123,14 +123,14 @@ fi
 The guard checks both `grep -q` (read-only) and `sudo grep -q` (with elevated permissions) to handle systems where `/etc/default/grub` requires root access. If the parameters are already present, the function exits early with a message rather than duplicating the entry.
-#### Additional notes & carifications
+#### Additional notes & clarifications
 1. **Regarding GCN Nomenclature**: Names like "GCN 1.0", "1.1", "1.2" were created by the press as a convenient abbreviation, since AMD only started officially numbering their GCN revisions (gen 1 to 4) later. The table now uses more standard terminology.
 2. **Relationship Between Drivers and Architectures**:
    * The `radeonsi` driver (OpenGL) and `RADV` (Vulkan) are siblings within the Mesa 3D project. Both depend on the [`amdgpu` kernel](https://docs.kernel.org/gpu/amdgpu/index.html).
    * The old [`radeon`](https://wiki.freedesktop.org/xorg/radeon/) driver (for TeraScale) is incompatible with modern Mesa drivers (`radeonsi`/`RADV`).
    * **Important milestone**: Starting from Linux kernel 6.19, the `amdgpu` driver will include support for older generations of [AMD GPUs](https://wiki.gentoo.org/wiki/AMDGPU) (such as TeraScale and early GCN) that were previously only supported by the `radeon` driver, unifying support.
-3. **Vulkan Support in RADV**: Mesa documentation indicates that [RADV supports Vulkan 1.4 for all GFX8 GPUs (GCN 3 onwards) and newer](https://docs.mesa3d.org/drivers/radv.html#supported-hardware). This includes RDNA 3 and RDNA 3.5 architectures, not just RDNA 4.
+3. **Vulkan Support in RADV**: Mesa documentation indicates that [RADV supports Vulkan 1.4 for all GFX8 GPUs (GCN 3 onwards) and newer](https://docs.mesa3d.org/drivers/radv.html#supported-hardware). This covers RDNA 4 as well as RDNA 3 and RDNA 3.5 architectures.
 4. **RDNA 3.5 Status**: It is an intermediate update that shares the architectural base of RDNA 3 (gfx11). The identifiers `gfx1150` and `gfx1151` correspond to this generation. Support in Mesa drivers and the kernel has been integrated progressively.
 ---
@@ -161,7 +161,7 @@ Starting with Turing, NVIDIA introduced the **open kernel module**. From driver
 | **Ada Lovelace**<br>*(AD100/102/103/104)* | 525.xx to 610+ | `nvidia` (**Open Module**) | **Vulkan 1.3** | **Yes** (Vulkan 1.3) | **CUDA 12.8+** | NVK added full Ada support recently. Proprietary driver still required if hardware Ray Tracing or DLSS 3 (Frame Generation) is needed, as NVK does not yet implement these proprietary extensions. |
 | **Blackwell**<br>*(GB100/102/202)* | [570.xx](https://docs.nvidia.com/datacenter/tesla/tesla-release-notes-570-211-01/index.html) to 610+ | `nvidia` (**Open Module**) | **Vulkan 1.3** | **Yes** (In development) | **CUDA 12.8+** | Latest generation architecture (RTX 5090/5080). NVK support is landing in the most recent kernel versions (6.12+) and Mesa (24.3+). Requires very updated `linux-firmware`. |
-#### 💡 Quick context glossary for documentation
+#### Quick context glossary
 * **Open Module:** Starting with driver 515, [NVIDIA releases code that interacts directly with the Linux kernel under MIT/GPL license](https://developer.nvidia.com/blog/nvidia-releases-open-source-gpu-kernel-modules/). However, the GPU still requires loading a proprietary closed microcode called **GSP (GPU System Processor)** to boot.
 * **NVK:** It is the open-source Vulkan driver developed by Red Hat and the community, integrated into the [Mesa project](https://docs.mesa3d.org/drivers/nvk.html). It's the 100% free alternative to `libGLX_nvidia.so`. Does not require NVIDIA proprietary driver installed to function (only kernel firmware).
@@ -187,14 +187,14 @@ When the script detects Intel or AMD hardware, it triggers a specific installati
 | **Intel Gen 8+** | `i915` | `iris` / `anv` | Installs [`intel-media-va-driver-non-free`](https://github.com/intel/media-driver). Modern, preferred backend for Broadwell+. |
 | **AMD GCN/RDNA** | `amdgpu` | `radeonsi` (GL) + `RADV` (VK) | Uses standard `va-driver-all`. Requires kernel param tuning for older GCN. |
-**Critical Consistency Check:**
+**Consistency Check:**
 The script enforces the installation of 32-bit Mesa libraries (`libgl1-mesa-dri:i386`) alongside the 64-bit packages. This is a mandatory requirement for running Proton (Steam) and Wine applications, which often rely on 32-bit OpenGL contexts even when running on a 64-bit OS.
 ---
 ### 7.**NVIDIA Driver Management & Kernel Compatibility**
-The NVIDIA driver installation process is inherently complex due to proprietary components, kernel version constraints, and DKMS (Dynamic Kernel Module Support) module compilation. This section outlines how the script navigates these challenges by distinguishing between stable and backports kernels, handling Blackwell architecture GPUs via the CUDA repository (production branches v590 / v595), and providing appropriate warnings for potential compatibility issues.
+The NVIDIA driver installation involves proprietary components, kernel version constraints, and DKMS (Dynamic Kernel Module Support) compilation. This section covers the choice between stable and backports kernels, Blackwell GPUs via the CUDA repository (production branches v590 / v595), and the warnings the script shows for compatibility issues.
 #### **Kernel Compatibility**
@@ -203,19 +203,19 @@ The NVIDIA driver installation process is inherently complex due to proprietary
 #### **Blackwell Architecture & CUDA v590/v595 (Production Branches)**
-* **Detection**: `_helpers.sh` function `is_nvidia_blackwell()` identifies GPUs via PCI IDs `10de:24xx`, `0x2900–0x29BF`, and `0x2B80–0x31FF`. The same check gates both CUDA branches — Blackwell is unsupported by Debian stable regardless of the selected CUDA version.
+* **Detection**: `_helpers.sh` function `is_nvidia_blackwell()` identifies GPUs via PCI IDs `10de:24xx`, `0x2900–0x29BF`, and `0x2B80–0x31FF`. The same check gates both CUDA branches: Blackwell is unsupported by Debian stable regardless of the selected CUDA version.
 * **Reason for v590/v595**: Debian 13 (Trixie) stable drivers only support up to v550, which lacks Blackwell (GB20x) architecture. The NVIDIA CUDA repository provides two production branches with unified driver packages: **v590**(current long-lived production, [590.48.01](https://download.nvidia.com/XFree86/Linux-x86_64/590.48.01/README/supportedchips.html)) and **v595** ([595.91.07](https://download.nvidia.com/XFree86/Linux-x86_64/595.91.07/README/supportedchips.html)newer production branch, same GB20x support with more recent fixes/features). Both branches expose the same unified metapackage and replace the need for a distro-packaged driver on Blackwell hardware.
-* **CUDA Repository Enablement**: On Debian 13 (Trixie) — the only release that exposes `590` and `595` (`_show_nvidia_version_menu` gates them behind `DEBIAN_VERSION == 13`) — the script enables the `nvidia-cuda` repository via `extrepo` (`sudo apt install -y extrepo` if missing, then `sudo extrepo enable nvidia-cuda`). After enabling, the script always runs an explicit `apt update`, then installs `nvidia-driver-pinning-<ver>` if available (official NVIDIA pinning, optional and version-specific for 590 vs 595), and finally installs the unified metapackage `nvidia-open` plus `firmware-nvidia-gsp` (pulled as a transitive dependency). No manual pinning file is written; if `apt install` fails, the real `apt` error is shown and the installation aborts.
+* **CUDA Repository Enablement**: On Debian 13 (Trixie), the only release that exposes `590` and `595` (`_show_nvidia_version_menu` gates them behind `DEBIAN_VERSION == 13`), the script enables the `nvidia-cuda` repository via `extrepo` (`sudo apt install -y extrepo` if missing, then `sudo extrepo enable nvidia-cuda`). After enabling, the script always runs an explicit `apt update`, then installs `nvidia-driver-pinning-<ver>` if available (official NVIDIA pinning, optional and version-specific for 590 vs 595), and finally installs the unified metapackage `nvidia-open` plus `firmware-nvidia-gsp` (pulled as a transitive dependency). No manual pinning file is written; if `apt install` fails, the real `apt` error is shown and the installation aborts.
 #### **Installation Flow**
 The NVIDIA flow is driven by `_install_nvidia_stack` (dispatcher in `modules/gpu.sh`):
-1. **Plan** — `_msg` with detected GPUs, then `_pause`.
+1. **Plan**: `_msg` with detected GPUs, then `_pause`.
 2. **Manage menu** (`_nvidia_manage_menu`): "Install / Change NVIDIA Driver Version" or "Remove NVIDIA Driver and Restore Nouveau".
 3. **Version menu** (`_show_nvidia_version_menu`): Debian 12 → v535 (Recommended) / v470 (Kepler); Debian 13 → v550 (Recommended) / v590 / v595 (NVIDIA CUDA Repo).
 4. **Dispatch by hardware**: Kepler → `nvidia-tesla-470-driver`; Fermi → veto with message; Turing+ → `_install_nvidia_standard` (Debian stable); Blackwell on Trixie → CUDA repo v590.
-5. **CUDA repo (590/595)**: two separate APT transactions — `nvidia-driver-pinning-<ver>` (version lock, mandatory) then `nvidia-open` (driver + open kernel modules, firmware via transitive dependency).
+5. **CUDA repo (590/595)**: two separate APT transactions: `nvidia-driver-pinning-<ver>` (version lock, mandatory) then `nvidia-open` (driver + open kernel modules, firmware via transitive dependency).
 6. **Secure Boot warning**: If Secure Boot is active (`mokutil --sb-state` reports `SecureBoot enabled`), the script displays a warning that the NVIDIA DKMS module is compiled but **NOT signed**. The user must sign the module with MOK or disable Secure Boot in BIOS before rebooting:
   ```
@@ -223,7 +223,7 @@ The NVIDIA flow is driven by `_install_nvidia_stack` (dispatcher in `modules/gpu
   You MUST sign the module with MOK or disable Secure Boot in BIOS before rebooting.
   ```
-   Installation continues — Secure Boot does not block DKMS compilation, but the module will fail to load until signed.
+   Installation continues: Secure Boot does not block DKMS compilation, but the module will fail to load until signed.
 7. **Post-install**: `/etc/modprobe.d/nvidia-wayland.conf` (written with `|| return 1` protection) + DKMS verification.
 > Note: Debian 12 (Bookworm) backports reached EOL (2026-08-09); the NVIDIA flow on Bookworm only uses the stable repository.
@@ -231,7 +231,7 @@ The NVIDIA flow is driven by `_install_nvidia_stack` (dispatcher in `modules/gpu
 ### 9.**NVIDIA Driver Compatibility Matrix**
-Depending on your GPU generation and your Debian ecosystem, you must select the appropriate legacy or current driver series. The following table details the verified compatibility matrix across different Debian versions and hardware architectures:
+Depending on your GPU generation and your Debian ecosystem, you must select the appropriate legacy or current driver series. The table below lists the verified compatibility across Debian versions and GPU generations:
 | Driver NVIDIA | Debian Version | Supported Architectures (Generations) | Notes |
 | :--- | :--- | :--- | :--- |
@@ -240,7 +240,7 @@ Depending on your GPU generation and your Debian ecosystem, you must select the
 | **[535.247.01](https://us.download.nvidia.com/XFree86/Linux-x86_64/535.247.01/README/supportedchips.html)** | **Debian 12** (Bookworm) | Maxwell to Ada Lovelace | Kepler support dropped completely. Standard for RTX 3000/4000 series. |
 | **[550.163.01](https://us.download.nvidia.com/XFree86/Linux-x86_64/550.163.01/README/supportedchips.html)** | **Debian 13** (Trixie) | Maxwell to Ada Lovelace | Current stable standard. Blackwell not officially supported yet. |
-#### **Critical Hardware Notes:**
+#### **Hardware Notes:**
 * **Kepler (GeForce vs. Quadro)**: The last driver supporting true Kepler architecture is version **470**. If a user has a GTX 680 or similar, they must stay on Debian 11 or use the 470 driver branch in Bookworm/Trixie manually.
 * **Fermi (GTX 400/500)**: Support ended with driver 390. These GPUs are incompatible with modern kernels and drivers beyond Debian 11.
@@ -262,7 +262,7 @@ fi
 ### 10. Performance Monitoring & Telemetry Tools
-To ensure the graphics stack is functioning correctly, `gpu.sh` offers an optional installation of telemetry tools. These allow users to verify GPU utilization, memory usage, and codec support post-installation.
+To check that the graphics stack works, `gpu.sh` offers an optional installation of telemetry tools. These allow users to verify GPU utilization, memory usage, and codec support post-installation.
 * **Universal ([`nvtop`](https://github.com/Syllo/nvtop))**:
  * A cross-platform tool that displays real-time metrics for NVIDIA, AMD, and Intel GPUs in a terminal interface (similar to `htop`).
@@ -272,7 +272,7 @@ To ensure the graphics stack is functioning correctly, `gpu.sh` offers an option
 * **Intel Specific ([`intel-gpu-tools`](https://github.com/ChrisCummins/intel-gpu-tools))**:
  * Only installed if the detected Intel hardware supports it (Gen 6+). Provides information on GPU usage via `inotify` or `/sys/class/drm`.
 * **Codec Verification ([`vainfo`](https://github.com/intel/libva-utils))**:
-  * The script runs `vainfo` to verify that VAAPI is correctly configured. This confirms whether the system can utilize hardware acceleration for video decoding (e.g., H.264, HEVC) via Intel QuickSync or AMD Video Core Plus.
+  * The script runs `vainfo` to verify that VAAPI is correctly configured. This confirms whether the system can use hardware acceleration for video decoding (e.g., H.264, HEVC) via Intel QuickSync or AMD Video Core Plus.
 **Installation Command Logic:**
@@ -287,4 +287,4 @@ if _confirm "Install Telemetry Tools"; then
 fi
 ```
-This modular approach ensures that users can verify their installation immediately after running `debianito`, providing confidence in the performance of their graphics stack.
+Users can run these tools right after `debianito` to confirm that the graphics stack works.
@@ -11,7 +11,7 @@ The **Kernel** module (`modules/kernel.sh`) manages which Linux kernel your syst
 | `rt` | Real-Time | `linux-image-rt-amd64` | Preempt-RT kernel for low-latency / audio production. Warns on NVIDIA. |
 | `cloud` | Cloud | `linux-image-cloud-amd64` | Minimal kernel for VMs, containers, and cloud images. |
-All variants install the matching **headers** package (`linux-headers-amd64`, `linux-headers-rt-amd64`, `linux-headers-cloud-amd64`) in the same transaction — critical for DKMS modules (NVIDIA, VirtualBox, ZFS).
+All variants install the matching **headers** package (`linux-headers-amd64`, `linux-headers-rt-amd64`, `linux-headers-cloud-amd64`) in the same transaction, which matters for DKMS modules (NVIDIA, VirtualBox, ZFS).
 > **Position in menu:** This is Option 7 in the current `debianito.sh` main menu. Previous documentation listed it as Option 6 (Backports only). The module was expanded to support RT and Cloud kernels after the initial release.
@@ -27,7 +27,7 @@ Debian Stable freezes its kernel at an LTS release (6.12 LTS on Trixie). This is
 The `trixie-backports` repository provides a **best-effort newer kernel** without moving the rest of the system to Testing. Debian backports kernels receive security updates but are not LTS themselves.
-This is why the menu shows `backports` only when `DEBIAN_VERSION == 13` and greys it out otherwise. Bookworm backports is intentionally not offered — its EOL was 2026-08-09 and the NVIDIA path on Bookworm no longer uses backports.
+This is why the menu shows `backports` only when `DEBIAN_VERSION == 13` and greys it out otherwise. Bookworm backports is intentionally not offered: its EOL was 2026-08-09 and the NVIDIA path on Bookworm no longer uses backports.
 ---
@@ -42,9 +42,9 @@ _install_kernel_package "linux-image-rt-amd64" "RT" ""
 Execution steps:
-1. **Availability check** — `apt-cache show <pkg>` must succeed. If the package does not exist for the current Debian version, a whiptail message `Kernel not available` is shown and the function returns.
+1. **Availability check**: `apt-cache show <pkg>` must succeed. If the package does not exist for the current Debian version, a whiptail message `Kernel not available` is shown and the function returns.
 2. **Hardware warnings** (flavour-specific):
-   - **Backports + NVIDIA** (`GPU_TYPE == "nvidia"`): `_confirm "Kernel" "WARNING: Backports kernel changes the kernel version. Your NVIDIA driver will need recompilation (DKMS)."`. Users can still proceed — DKMS will rebuild on next boot if headers match.
+   - **Backports + NVIDIA** (`GPU_TYPE == "nvidia"`): `_confirm "Kernel" "WARNING: Backports kernel changes the kernel version. Your NVIDIA driver will need recompilation (DKMS)."`. Users can still proceed: DKMS will rebuild on next boot if headers match.
   - **RT + NVIDIA**: `_msg "Kernel — RT" "Ensure your NVIDIA driver supports the RT kernel. Some proprietary drivers may not work correctly."`. Not a blocker, but informs that some closed drivers fail with PREEMPT_RT.
 3. **Version resolution** for the confirmation dialog:
@@ -57,7 +57,7 @@ Execution steps:
   ```
   The dialog shows `Image: linux-image-amd64 (6.12.22-1)` + `Headers: linux-headers-amd64 (6.12.22-1)` + `From: Trixie-backports` when a backports flag is present.
-4. **User confirmation** — `whiptail --yesno "Install Backports kernel? Image: ... Headers: ..."` with the version string. Declining aborts with `Skipping.`.
+4. **User confirmation**: `whiptail --yesno "Install Backports kernel? Image: ... Headers: ..."` with the version string. Declining aborts with `Skipping.`.
 5. **Atomic install**:
   ```bash
@@ -66,8 +66,8 @@ Execution steps:
   sudo apt install -y linux-image-cloud-amd64 linux-headers-cloud-amd64
   ```
-   Both image and headers are passed in a **single `apt` transaction**. This guarantees the symbol tables match and DKMS can rebuild. The helper `_run_cmd "Kernel"` prints the command, captures the exit code, and pauses for the user to review output.
+   Both image and headers are passed in a **single `apt` transaction**. This keeps the symbol tables matched so DKMS can rebuild. The helper `_run_cmd "Kernel"` prints the command, captures the exit code, and pauses for the user to review output.
-6. **Post-install** — prints `Backports kernel installed. Reboot to use it.` and pauses. The new kernel is added to `/boot` alongside the old one; GRUB will show both at next boot. The script does not remove the old kernel — rollback is simply rebooting into the previous entry.
+6. **Post-install**: prints `Backports kernel installed. Reboot to use it.` and pauses. The new kernel is added to `/boot` alongside the old one; GRUB will show both at next boot. The script does not remove the old kernel; rollback is simply rebooting into the previous entry.
 ---
@@ -101,9 +101,9 @@ show_kernel_menu() {
 Key details:
- **Backports visibility** — The `backports` entry is only appended when `DEBIAN_VERSION == 13`. On Bullseye/Bookworm it does not appear.
+- **Backports visibility**: The `backports` entry is only appended when `DEBIAN_VERSION == 13`. On Bullseye/Bookworm it does not appear.
- **Backports guard** — Selecting `backports` without backports enabled shows a message pointing to **Option 4 (Configure Repositories)**. No install is attempted.
+- **Backports guard**: Selecting `backports` without backports enabled shows a message pointing to **Option 4 (Configure Repositories)**. No install is attempted.
- **Loop** — The menu is a `while true` loop; the user can install multiple variants sequentially (e.g., Stable + RT) before returning with `back` or `ESC`.
+- **Loop**: The menu is a `while true` loop; the user can install multiple variants sequentially (e.g., Stable + RT) before returning with `back` or `ESC`.
 ---
@@ -113,20 +113,20 @@ Key details:
 | ----------- | -------------- |
 | **Pre-flight `is_backports_enabled`** | `utils.sh:is_backports_enabled` greps `/etc/apt/sources.list` and `/etc/apt/sources.list.d/*.sources` / `*.list` for `trixie-backports`. Prevents `apt -t` from failing with `E: Release not found`. |
 | **NVIDIA RT warning** | `utils.sh:GPU_TYPE` is set on demand by `detect_gpu` (lspci, via `_ensure_state_detected`). RT kernels change scheduling semantics; some `nvidia.ko` builds reject `PREEMPT_RT`. |
-| **Atomic image+headers** | Both packages in one `apt` call. If headers are missing, `dkms` will fail at boot — so they are never installed separately. |
+| **Atomic image+headers** | Both packages in one `apt` call. If headers are missing, `dkms` will fail at boot, so they are never installed separately. |
 | **Fallback preservation** | `apt` never removes the running kernel. `/boot` retains `vmlinuz-*` and `initrd.img-*` for both. GRUB keeps both entries; if the new kernel panics, select the old one. |
 | **Version-aware messaging** | The confirmation dialog always shows the exact version string (`apt-cache madison` / `apt-cache show`) so users know they are not reinstalling the same package. |
-GRUB update is **not** explicitly called — `linux-image-*` postinst triggers `update-grub` (or `kernel-install` on systemd-boot) automatically. If GRUB is broken, use **Option 12 (Boot Rescue + GRUB)** to rebuild it.
+GRUB update is **not** explicitly called: `linux-image-*` postinst triggers `update-grub` (or `kernel-install` on systemd-boot) automatically. If GRUB is broken, use **Option 12 (Boot Rescue + GRUB)** to rebuild it.
 ---
 ## 6. Interconnection with Other Modules
- **Option 4: Repositories** — Must enable `trixie-backports` before `Kernel → backports` is usable. The kernel menu explicitly checks `is_backports_enabled` and directs the user there if missing.
+- **Option 4: Repositories**: Must enable `trixie-backports` before `Kernel → backports` is usable. The kernel menu explicitly checks `is_backports_enabled` and directs the user there if missing.
- **Option 5: Firmware** — Newer kernels expose new hardware IDs (e.g., `8086:7e40` for Panther Lake). Without updated `firmware-linux-nonfree` or `firmware-iwlwifi`, the new kernel will show the device but fail to load firmware. Run Firmware after a kernel upgrade if WiFi/storage is not recognized.
+- **Option 5: Firmware**: Newer kernels expose new hardware IDs (e.g., `8086:7e40` for Panther Lake). Without updated `firmware-linux-nonfree` or `firmware-iwlwifi`, the new kernel will show the device but fail to load firmware. Run Firmware after a kernel upgrade if WiFi/storage is not recognized.
- **Option 6: Graphics Drivers** — NVIDIA `dkms` needs the exact `linux-headers-*` version. The atomic install ensures headers match. On Bookworm the NVIDIA path deliberately avoids backports kernels; on Trixie a backports kernel + Maxwell/Pascal GPU is forced to the stable NVIDIA driver (`v550`) to avoid `v590` incompatibility.
+- **Option 6: Graphics Drivers**: NVIDIA `dkms` needs the exact `linux-headers-*` version. The atomic install ensures headers match. On Bookworm the NVIDIA path deliberately avoids backports kernels; on Trixie a backports kernel + Maxwell/Pascal GPU is forced to the stable NVIDIA driver (`v550`) to avoid `v590` incompatibility.
- **Gaming (`gaming.sh`)** — The backports kernel is sometimes recommended for gaming (scheduler latency, `SCHED_EXT`), but not required. Benchmarks show <3% difference for most titles; enable it only for newer hardware that needs it.
+- **Gaming (`gaming.sh`)**: The backports kernel is sometimes recommended for gaming (scheduler latency, `SCHED_EXT`), but not required. Benchmarks show <3% difference for most titles; enable it only for newer hardware that needs it.
 ---
@@ -146,7 +146,7 @@ If the new kernel fails to boot, hold `ESC` (or `Shift` on BIOS) at power-on, se
 ## References
- [Debian Backports — backports.debian.org](https://backports.debian.org/)
+- [Debian Backports: backports.debian.org](https://backports.debian.org/)
 - [Debian Kernel Handbook](https://kernel-handbook.alioth.debian.org/)
- [PREEMPT_RT — wiki.debian.org/RealTime](https://wiki.debian.org/RealTime)
+- [PREEMPT_RT: wiki.debian.org/RealTime](https://wiki.debian.org/RealTime)
- [Installing a new kernel — wiki.debian.org/DebianKernel](https://wiki.debian.org/DebianKernel)
+- [Installing a new kernel: wiki.debian.org/DebianKernel](https://wiki.debian.org/DebianKernel)
@@ -1,4 +1,4 @@
-# Debianito — Quick Start Visual Guide
+# Debianito: Quick Start Visual Guide
 > **Scope:** Fresh Debian 11 / 12 / 13 installation → fully configured desktop in ~15-20 minutes.
 > **Prerequisites:** Normal user with `sudo` access. Do **not** run the script as root.
@@ -18,13 +18,25 @@ The script automatically checks for `whiptail` and `lsb-release`, installs them
 > ![Script](/media/gift/script.gif)
 With no flags the script runs interactively. Three flags change that (full table in the [README](../README.md#command-line-usage)):
 ```bash
 ./debianito.sh --yes                     # auto-confirm prompts; menus still display
 ./debianito.sh --yes --allow-destructive # also unblock branch migration
 ./debianito.sh --help                    # show usage and exit
 ```
 `--yes` auto-confirms prompts, but the menus still display and still need arrow keys and ENTER. By itself it does not reach branch migration (menu `4  [ADVANCED] Upgrade system branch`): that operation can leave the system unbootable, so the script reports that `--allow-destructive` is required. `DEBIANITO_PROFILE=1 ./debianito.sh` stamps each boot step to stderr with a timestamp, which makes before/after comparisons possible. An unknown option exits with status 2.
 Package installs are batched behind a single confirmation: the script lists what it is about to install (the first 15 package names, plus a count of the rest) and asks you to proceed. With `--yes` these confirmations are accepted automatically.
 ---
 ## Recommended Order
-Each step builds on the previous one. Steps 1-5 + 10 are the essential path; 6-9 are optional.
+Each step builds on the previous one. Steps 1-6 are the essential path; steps 7-10 are optional.
-### Step 1 — Know Your System
+### Step 1: Know Your System
 **Menu:** `1  System Information`
@@ -39,11 +51,11 @@ You will see:
 - Storage topology (NVMe / SSD / HDD / USB-SD)
 - Display server (Wayland / X11 / tty) and desktop environment
-Remember the **GPU line** (Intel / AMD / NVIDIA) and any **WiFi chipset** — you will need them in Steps 4-5.
+Remember the **WiFi chipset** for the firmware mapping in Step 5, and the **GPU line** (Intel / AMD / NVIDIA) for the drivers in Step 6.
 > ![Script](/media/screenshots/01-system-info.png) System Information dialog with hardware summary.
-### Step 2 — Fix Permissions Early (Optional but Recommended)
+### Step 2: Fix Permissions Early (Optional but Recommended)
 **Menu:** `2  User Privileges & Feedback`
@@ -54,12 +66,12 @@ A sub-menu with four toggles:
 | Sudo group membership | `usermod -aG sudo $USER` | Fresh install where the first user is not in `sudo` |
 | Passwordless sudo | Creates `/etc/sudoers.d/$USER-nopasswd` with `NOPASSWD` for `apt`, `systemctl`, etc. | Lab / personal machine; skip on shared systems |
 | Repair home ownership | `chown -R $USER:$USER $HOME` | Home files owned by root after a mishandled `sudo` |
-| Sudo password feedback | Writes `Defaults pwfeedback` to `/etc/sudoers.d/pwfeedback` — shows `****` while typing | **Enable now** to avoid typos during the many installs that follow |
+| Sudo password feedback | Writes `Defaults pwfeedback` to `/etc/sudoers.d/pwfeedback` (typing then shows `****`) | **Enable now** to avoid typos during the many installs that follow |
 > ![Script](/media/screenshots/02-user-privileges.png) User Privileges & Feedback menu.
 > ![Script](/media/screenshots/02b-pwfeedback.png) Confirmation dialog for "Sudo Password Feedback" with asterisk preview.
-### Step 3 — System Preferences (Optional)
+### Step 3: System Preferences (Optional)
 **Menu:** `3  System Preferences`
@@ -70,13 +82,13 @@ A sub-menu with four toggles:
 4  Back to main menu
 ```
- **Date, Time & Timezone** — Runs `dpkg-reconfigure tzdata` and then `_ensure_time_synced` (NTP + `systemd-timesyncd`). Fix timezone before `apt update` — a wrong clock breaks GPG verification.
+- **Date, Time & Timezone**: Runs `dpkg-reconfigure tzdata` and then `_ensure_time_synced` (NTP + `systemd-timesyncd`). Fix timezone before `apt update`: a wrong clock breaks GPG verification.
- **Language, Locales & Keyboard** — Runs `dpkg-reconfigure locales` and `keyboard-configuration`. Requires re-login to apply `LANG`.
+- **Language, Locales & Keyboard**: Runs `dpkg-reconfigure locales` and `keyboard-configuration`. Requires re-login to apply `LANG`.
- **Audio & Sound Stack** — Checklist with `pipewire-audio` (or `pipewire` on Bullseye), `alsa-utils`, `pavucontrol` (hidden on TTY), `pulsemixer`, `playerctl`. PipeWire on Trixie offers a Backports vs Stable choice and installs Bluetooth Hi-Res codecs (`LDAC`, `aptX`, `AAC`). See [System Preferences](system_prefs.md).
+- **Audio & Sound Stack**: Checklist with `pipewire-audio` (or `pipewire` on Bullseye), `alsa-utils`, `pavucontrol` (hidden on TTY), `pulsemixer`, `playerctl`. PipeWire on Trixie offers a Backports vs Stable choice and installs Bluetooth Hi-Res codecs (`LDAC`, `aptX`, `AAC`). See [System Preferences](system_prefs.md).
 > ![Script](/media/screenshots/03-system-prefs.png) System Preferences menu.
-### Step 4 — Configure Repositories (Required)
+### Step 4: Configure Repositories (Required)
 **Menu:** `4  Configure Repositories`
@@ -88,32 +100,32 @@ A sub-menu with four toggles:
 5  Back to main menu
 ```
-1. Choose **1. Enable Contrib & Non-Free** — adds `contrib`, `non-free`, `non-free-firmware` (Bookworm/Trixie). Required for firmware, NVIDIA drivers, and Steam (`contrib`). The script handles both `/etc/apt/sources.list` (classic) and `/etc/apt/sources.list.d/debian.sources` (DEB822) and validates via `apt update` with automatic rollback.
+1. Choose **1. Enable Contrib & Non-Free**: adds `contrib`, `non-free`, `non-free-firmware` (Bookworm/Trixie). Required for firmware, NVIDIA drivers, and Steam (`contrib`). The script handles both `/etc/apt/sources.list` (classic) and `/etc/apt/sources.list.d/debian.sources` (DEB822) and validates via `apt update` with automatic rollback.
-2. Choose **3. Setup/Update Backports** — answers `Yes` to enable `trixie-backports` / `bookworm-backports` in a separate file (`debian-backports.sources` or `.list`). Backports gives newer kernels, Mesa, and firmware. See [Configure Repositories](repos_config.md).
+2. Choose **3. Setup/Update Backports**: answers `Yes` to enable `trixie-backports` / `bookworm-backports` in a separate file (`debian-backports.sources` or `.list`). Backports gives newer kernels, Mesa, and firmware. See [Configure Repositories](repos_config.md).
 ⚠️ Without `non-free` and `contrib`, Steps 5 and 8 will fail. Do not skip.
 > ![Script](/media/screenshots/04-repos.png) Repositories menu.
 > ![Script](/media/screenshots/04b-backports.png) Backports confirmation dialog.
-### Step 5 — Install Firmware & Wireless Drivers
+### Step 5: Install Firmware & Wireless Drivers
 **Menu:** `5  Firmware, Wireless & Bluetooth`
 The script:
 - Scans **all** network hardware (PCI `lspci -nn` + USB `lsusb`, filtered for Realtek/Intel/Mediatek/Atheros/Qualcomm) and Bluetooth controllers
- Maps vendors to packages: `firmware-iwlwifi`, `firmware-realtek`, `firmware-mediatek`, `firmware-atheros`, `firmware-intel-misc` — plus `firmware-linux-nonfree` as the base meta-package
+- Maps vendors to packages: `firmware-iwlwifi`, `firmware-realtek`, `firmware-mediatek`, `firmware-atheros`, `firmware-intel-misc`, plus `firmware-linux-nonfree` as the base meta-package
 - Builds a plan showing detected controllers and planned packages, including Bluetooth handling (KDE → `bluedevil`, XFCE → `blueman`, GNOME → built-in, plus `pipewire-pulse`/`wireplumber` if PipeWire is active)
 - Asks for confirmation before installing; offers Stable vs Backports for the base firmware
-Accept the plan it shows — it is based on your actual hardware. Broadcom wireless (if present) is handled via `broadcom-sta-dkms` with DKMS build checks and `update-initramfs` + `modprobe wl`.
+Accept the plan it shows: it is based on your actual hardware. Broadcom wireless (if present) is handled via `broadcom-sta-dkms` with DKMS build checks and `update-initramfs` + `modprobe wl`.
-⚠️ You need internet for this step. If WiFi does not work after firmware install, **reboot** first — the driver needs a fresh load.
+⚠️ You need internet for this step. If WiFi does not work after firmware install, **reboot** first: the driver needs a fresh load.
 > ![Script](/media/screenshots/05-firmware-plan.png) Firmware plan dialog with hardware + package list.
-### Step 6 — Install Graphics Drivers
+### Step 6: Install Graphics Drivers
 **Menu:** `6  Graphics Drivers & Mesa Stack`
@@ -124,11 +136,11 @@ Whiptail radiolist with two options:
 2  NVIDIA Drivers
 ```
-#### Path A — Radeon/Intel Mesa
+#### Path A: Radeon/Intel Mesa
 Shows a plan with detected GPUs (`Intel firmware + intel-media-va-driver-non-free` or `i965-va-driver-shaders` for Gen7-, `firmware-amd-graphics` for AMD, plus `Mesa Vulkan/OpenGL/VA-API`). Offers legacy AMD GCN 1.0/1.1 migration to `amdgpu` via GRUB params (`radeon.si_support=0 ... amdgpu.si_support=1`). Installs Mesa from Backports or Stable (`_install_mesa_backports`), verifies `mesa-vulkan-drivers`, and offers vendor-specific telemetry (`radeontop`, `intel-gpu-tools`, `vainfo`).
-#### Path B — NVIDIA Drivers
+#### Path B: NVIDIA Drivers
 Shows detected NVIDIA GPUs and a two-stage menu:
@@ -137,13 +149,13 @@ Shows detected NVIDIA GPUs and a two-stage menu:
   - Bookworm: `v535` (Recommended) or `v470` (Kepler legacy via `nvidia-tesla-470-driver`)
   - Trixie: `v550` (Debian stable, Recommended), `v590` or `v595` (NVIDIA CUDA Repo with `cuda-keyring` + `nvidia-open` + `firmware-nvidia-gsp`)
-The script auto-detects the GPU architecture (`kepler` / `fermi` / `maxwell` / `pascal` / `turing` / `ampere` / `ada` / `blackwell`) and enforces compatibility — e.g., Blackwell requires `v590+` on Trixie, Maxwell/Pascal on Trixie + backports kernel is forced to `v550` stable, Fermi is vetoed on Bookworm/Trixie with an explanatory message.
+The script auto-detects the GPU architecture (`kepler` / `fermi` / `maxwell` / `pascal` / `turing` / `ampere` / `ada` / `blackwell`) and enforces compatibility. For example, Blackwell requires `v590+` on Trixie, Maxwell/Pascal on Trixie + backports kernel is forced to `v550` stable, Fermi is vetoed on Bookworm/Trixie with an explanatory message.
 > ![Script](/media/screenshots/06-gpu-choice.png) GPU type selector (Radeon/Intel vs NVIDIA).
 After installation, **reboot** before testing. NVIDIA drivers need a fresh kernel load.
-### Step 7 — Kernel Configuration (Optional)
+### Step 7: Kernel Configuration (Optional)
 **Menu:** `7  Kernel`
@@ -155,17 +167,17 @@ cloud      Install linux-image-cloud-amd64
 back       Return to main menu
 ```
- **Stable** — default Debian kernel (6.12 LTS on Trixie).
+- **Stable**: default Debian kernel (6.12 LTS on Trixie).
- **Backports** — only on Trixie; requires `trixie-backports` enabled in Step 4. Newer kernel (e.g., 7.x) for Intel Arrow Lake / AMD Zen 5, Battlemage D3cold, etc.
+- **Backports**: only on Trixie; requires `trixie-backports` enabled in Step 4. Newer kernel (e.g., 7.x) for Intel Arrow Lake / AMD Zen 5, Battlemage D3cold, etc.
- **RT** — Preempt-RT low-latency kernel. Warns if `GPU_TYPE == nvidia` (proprietary drivers may not support RT).
+- **RT**: Preempt-RT low-latency kernel. Warns if `GPU_TYPE == nvidia` (proprietary drivers may not support RT).
- **Cloud** — minimal kernel for VMs/containers (`linux-image-cloud-amd64`).
+- **Cloud**: minimal kernel for VMs/containers (`linux-image-cloud-amd64`).
 Each variant installs the matching `linux-headers-*` package atomically (`sudo apt install -y [-t trixie-backports] linux-image-* linux-headers-*`). The script warns about DKMS recompilation if NVIDIA is present.
-> ![Script](/media/screenshots/07-kernel.png) — Kernel menu with four variants.
+> ![Script](/media/screenshots/07-kernel.png) Kernel menu with four variants.
 > See [kernel](kernel.md) for backports rationale and bootloader details.
-### Step 8 — Gaming Setup (Optional)
+### Step 8: Gaming Setup (Optional)
 **Menu:** `8  Gaming Setup`
@@ -194,7 +206,7 @@ A single checklist with all options:
 > ![Script](/media/screenshots/08-gaming.png) Gaming checklist with i386 + Steam + MangoHud checked.
 > See [gaming](gaming.md) and [retroarch](retroarch.md).
-### Step 9 — ZRAM Compressed Swap (Optional)
+### Step 9: ZRAM Compressed Swap (Optional)
 **Menu:** `9  ZRAM`
@@ -205,15 +217,15 @@ A single checklist with all options:
 4  Back to main menu
 ```
- **View** — Shows `/etc/default/zramswap` (`ALGO`, `SIZE`, `PRIORITY`) and `zramctl` output.
+- **View**: Shows `/etc/default/zramswap` (`ALGO`, `SIZE`, `PRIORITY`) and `zramctl` output.
- **Create / Reconfigure** — Choice of `lz4` (fastest, gaming) vs `zstd` (better ratio). Recommended size is 50% of RAM (≤8 GB) or 4096 MB fixed (>8 GB), configurable. Writes to `/etc/default/zramswap` (`ALGO`, `SIZE`, `PRIORITY=100`) and `systemctl restart zramswap || true`. Priority 100 ensures ZRAM is used before any disk swap (priority 10).
+- **Create / Reconfigure**: Choice of `lz4` (fastest, gaming) vs `zstd` (better ratio). Recommended size is 50% of RAM (≤8 GB) or 4096 MB fixed (>8 GB), configurable. Writes to `/etc/default/zramswap` (`ALGO`, `SIZE`, `PRIORITY=100`) and `systemctl restart zramswap || true`. Priority 100 ensures ZRAM is used before any disk swap (priority 10).
- **Remove** — `systemctl stop zramswap`, `swapoff /dev/zram0`, `modprobe -r zram`, `apt purge zram-tools`, removes `/etc/default/zramswap`.
+- **Remove**: `systemctl stop zramswap`, `swapoff /dev/zram0`, `modprobe -r zram`, `apt purge zram-tools`, removes `/etc/default/zramswap`.
 > ![Script](/media/screenshots/09-zram-algo.png) Algorithm choice (lz4 vs zstd).
 > ![Script](/media/screenshots/09b-zram-status.png) `zramctl` status output in whiptail.
 > See [zram](zram.md).
-### Step 10 — Swap Management (Optional)
+### Step 10: Swap Management (Optional)
 **Menu:** `10  Swap Management`
@@ -234,7 +246,7 @@ A single checklist with all options:
 > ![Script](/media/screenshots/10b-swap-status.png) Swap status.
 > See [swap](swap.md).
-### Step 11 — Install Programs and Software
+### Step 11: Install Programs and Software
 **Menu:** `11  Install Programs and Software` → `0  Essential Pack`
@@ -261,17 +273,17 @@ After this, browse the other categories as needed:
 > ![Script](/media/screenshots/11-programs.gif) Category menu with 0-14 options.
 > ![Script](/media/screenshots/11b-essential-pack.png) Essential Pack confirmation.
-### Step 12 — Boot Rescue
+### Step 12: Boot Rescue
 **Menu:** `12  Boot Rescue + GRUB`
- **GRUB boot menu settings** — 4 presets (hidden 0s / 3s / 5s / custom) writing `GRUB_TIMEOUT`, `GRUB_TIMEOUT_STYLE`, `GRUB_RECORDFAIL_TIMEOUT`, `GRUB_DISABLE_OS_PROBER` to `/etc/default/grub.d/99_script_override.cfg` with `update-grub` + backup/rollback.
+- **GRUB boot menu settings**: 4 presets (hidden 0s / 3s / 5s / custom) writing `GRUB_TIMEOUT`, `GRUB_TIMEOUT_STYLE`, `GRUB_RECORDFAIL_TIMEOUT`, `GRUB_DISABLE_OS_PROBER` to `/etc/default/grub.d/99_script_override.cfg` with `update-grub` + backup/rollback.
- **UEFI Secure Boot repair** — reinstalls `shim-signed`, `grub-efi-amd64-signed`, `linux-image-amd64`, runs `grub-install` + `update-grub` (UEFI only, checked via `/sys/firmware/efi` + `mokutil`).
+- **UEFI Secure Boot repair**: reinstalls `shim-signed`, `grub-efi-amd64-signed`, `linux-image-amd64`, runs `grub-install` + `update-grub` (UEFI only, checked via `/sys/firmware/efi` + `mokutil`).
- **Initramfs regeneration** — `update-initramfs -u -k all || true`.
+- **Initramfs regeneration**: `update-initramfs -u -k all || true`.
 > See [boot](boot.md).
-### Step 13 — Desktop & Display
+### Step 13: Desktop & Display
 **Menu:** `13  Desktop & Display`
@@ -281,8 +293,8 @@ After this, browse the other categories as needed:
 3  Back to main menu
 ```
- **Desktop Environment** — pick one of **XFCE** (full / minimal / Wayland `labwc` on Trixie / custom checklist), **LXDE** (full / core), **GNOME** (full / core) or **KDE Plasma** (full / minimal). Each environment installs from its own module in `modules/desktops/` (lazy-loaded). XFCE installs polkit rules (`85-suspend.rules`, `89-backlight.rules`) + `backlight` group; GNOME/KDE preseed the display manager while keeping any already-configured one as default. After the install, the script offers the PipeWire audio stack if none is present.
+- **Desktop Environment**: pick one of **XFCE** (full / minimal / Wayland `labwc` on Trixie / custom checklist), **LXDE** (full / core), **GNOME** (full / core) or **KDE Plasma** (full / minimal). Each environment installs from its own module in `modules/desktops/` (lazy-loaded). XFCE installs polkit rules (`85-suspend.rules`, `89-backlight.rules`) + `backlight` group; GNOME/KDE preseed the display manager while keeping any already-configured one as default. After the install, the script offers the PipeWire audio stack if none is present.
- **Display Manager** — LightDM (GTK greeter, user list, autologin), GDM3 (user list, autologin, NVIDIA Wayland override via `61-gdm.rules → /dev/null`), SDDM (autologin with session auto-detection `plasmawayland → lxqt-wayland → plasma → lxqt`), greetd (base / tuigreet / gtkgreet / nwg-hello / wlgreet — manual `/etc/greetd/config.toml` required).
+- **Display Manager**: LightDM (GTK greeter, user list, autologin), GDM3 (user list, autologin, NVIDIA Wayland override via `61-gdm.rules → /dev/null`), SDDM (autologin with session auto-detection `plasmawayland → lxqt-wayland → plasma → lxqt`), greetd (base / tuigreet / gtkgreet / nwg-hello / wlgreet; manual `/etc/greetd/config.toml` required).
 > See [Desktop & Display](desktops_display.md).
@@ -301,7 +313,7 @@ After this, browse the other categories as needed:
   systemctl status bluetooth # Bluetooth active?
   ```
-3. For gaming, enable `i386` was handled — verify with `dpkg --print-foreign-architectures | grep i386`.
+3. For gaming, the script adds the `i386` architecture when you check `steam`, `lutris` or `i386`; verify with `dpkg --print-foreign-architectures | grep i386`.
 ---
@@ -313,6 +325,6 @@ After this, browse the other categories as needed:
 | **Black screen after NVIDIA + Wayland (GNOME/GDM3)** | At login, select *GNOME on Xorg* (gear icon) or disable Wayland: `sudo nano /etc/gdm3/daemon.conf` → `WaylandEnable=false`. The script only warns about Debian bug #1109409, it does not force X11. |
 | **GRUB menu hidden and cannot enter** | Hold `ESC` immediately after power-on. Or boot a live USB, `chroot`, and run `12  Boot Rescue → GRUB boot menu settings → Show 5 seconds`. |
 | **Steam fails to start** | Verify `i386` is enabled: `dpkg --print-foreign-architectures`. Check `contrib` is in `/etc/apt/sources.list`. Re-run `8  Gaming Setup` and ensure the checklist had `i386` + `steam` checked. |
-| **greetd installed but cannot log in** | This is expected — you must create `/etc/greetd/config.toml` manually. See `man greetd` and `man 5 greetd-sessions`. |
+| **greetd installed but cannot log in** | This is expected: you must create `/etc/greetd/config.toml` manually. See `man greetd` and `man 5 greetd-sessions`. |
 | **Bluetooth tray icon missing** | Reboot or `systemctl restart bluetooth`. Ensure `bluez`, `bluedevil` (KDE) or `blueman` (XFCE) is installed. For PipeWire, check `systemctl --user status pipewire pipewire-pulse wireplumber`. |
 | **PipeWire crackling / no Bluetooth Hi-Res codec** | Re-run `3  System Preferences → Audio & Sound → PipeWire Audio Stack`. Verify `libldacbt-*`, `libopenaptx0`, `libfdk-aac2t64` are installed (`dpkg -l \| grep -E 'ldac\|aptx\|fdk'`). |
@@ -2,23 +2,23 @@
 ### 1. What Does This Component Do?
-The repository configuration module is the foundational engine of Debianito that establishes and maintains a secure, up-to-date package management environment for your Debian system. It performs **idempotent, atomic operations** to configure APT sources with precision while protecting against corruption through automatic rollback mechanisms.
+The repository configuration module sets up and maintains the APT sources of your Debian system. Each change is written atomically, backed up beforehand and rolled back automatically if the following `apt update` fails.
-At its core, this component:
+It:
 - Detects your current repository format (Classic `.list` vs modern DEB822 `.sources`)
 - Backs up existing configurations before any modifications
- Enables critical non-free components required for hardware drivers and proprietary software
+- Enables the non-free components required for hardware drivers and proprietary software
 - Integrates Debian Backports to access newer kernels and firmware packages
 - Validates changes through `apt update` with automatic restoration on failure
-This is not just about "adding repositories"—it's about **system integrity assurance** that enables all other configuration options (GPU drivers, kernel upgrades, gaming setup) to function correctly.
+Every other configuration option (GPU drivers, kernel upgrades, gaming setup) needs this module to work first.
 ---
 ### 2. Supported Injection Formats
-The script intelligently adapts to your Debian version and existing repository structure:
+The script adapts to your Debian version and existing repository structure:
 #### Classic Format (`/etc/apt/sources.list`)
@@ -33,7 +33,7 @@ deb https://deb.debian.org/debian bookworm main contrib non-free non-free-firmwa
 #### Modern DEB822 Format (`/etc/apt/sources.list.d/debian.sources`)
- **Structure**: Declarative YAML-like format with `Types`, `URIs`, and `Suites` blocks
+- **Structure**: Declarative RFC-822 style format with `Types`, `URIs`, and `Suites` blocks
 - **Use Case**: Debian 13 (Trixie) default, future-proofing for newer releases
 - **Characteristics**: Machine-parseable, structured, supports complex repository hierarchies
 - **Example**:
@@ -50,7 +50,7 @@ Components: main contrib non-free non-free-firmware
 The script automatically detects your current format and offers migration options:
 - On Debian 13 (Trixie): Prompts to migrate TO DEB822 or stay with Classic
- Format changes are atomic—backup is created before any modification
+- Format changes are atomic: a backup is created before any modification
 - Old files are renamed with `.disabled` extension rather than deleted
 ---
@@ -160,7 +160,7 @@ The script enables specific APT component branches that are essential for hardwa
 | **non-free** | Non-free firmware and proprietary software | NVIDIA GPU drivers, Wi-Fi firmware | Required for hardware support |
 | **non-free-firmware** | Firmware blobs (Wi-Fi, Bluetooth, etc.) | Wireless adapters, embedded chips | **Critical from Debian 12+** |
-#### Why `non-free-firmware` is Vital (Debian 12+)
+#### Why `non-free-firmware` Is Required (Debian 12+)
 Starting with Debian Bookworm (12.0), the `non-free-firmware` component was separated into its own repository branch:
@@ -174,10 +174,10 @@ deb https://deb.debian.org/debian bookworm main contrib non-free non-free-firmwa
 **Impact of Missing `non-free-firmware`:**
- ❌ Wi-Fi adapters won't work without firmware blobs
+- Wi-Fi adapters won't work without firmware blobs
- ❌ Bluetooth devices may fail to initialize
+- Bluetooth devices may fail to initialize
- ❌ Some GPU drivers require proprietary microcode
+- Some GPU drivers require proprietary microcode
- ❌ Embedded hardware (Raspberry Pi, etc.) becomes unusable
+- Embedded hardware (Raspberry Pi, etc.) becomes unusable
 The script ensures all four components are present because:
@@ -189,7 +189,7 @@ The script ensures all four components are present because:
 ### 5. Support for Debian Backports
-The backports integration is a sophisticated feature that enables access to newer, tested packages without compromising system stability:
+Backports give access to newer, tested packages without compromising system stability:
 #### Detection Logic (`detect_backports_status` & `detect_backports_location`)
@@ -243,7 +243,7 @@ The backports integration is a sophisticated feature that enables access to newe
 #### Why Enable Backports?
-The script includes a detailed explanation because backports enable critical features:
+The script explains this in its confirmation dialog because backports change what you get for three components:
 | Feature | Without Backports | With Backports |
 | --------- | ------------------- | ---------------- |
@@ -18,16 +18,16 @@ When installed via `apt`, RetroArch uses these locations:
 Because the core and info directories are owned by root, you cannot write to them without `sudo`.  
 You have two options:
-1. **Manual installation** – download cores and info files yourself and copy them with `sudo`.  
+1. **Manual installation**: download cores and info files yourself and copy them with `sudo`.  
 2. **Reconfigure RetroArch** to use user‑writable folders, then use the built‑in **Core Downloader**.
 Both methods work; choose the one that suits you best.
 ---
-## Method 1 – Manual Core Installation (Recommended for Reliability)
+## Method 1: Manual Core Installation (Recommended for Reliability)
-This method guarantees that you can add any core, even if the online updater is blocked.
+This method works for any core, even when the online updater is blocked.
 ### 1. Download and Install the Core (`.so`)
@@ -41,7 +41,7 @@ sudo mv ppsspp_libretro.so /usr/lib/x86_64-linux-gnu/libretro/
 rm ppsspp_libretro.so.zip
 ```
-> **Replace `ppsspp` with any core name** – e.g., `mame_libretro`, `dolphin_libretro`, etc.  
+> **Replace `ppsspp` with any core name**: e.g., `mame_libretro`, `dolphin_libretro`, etc.  
 > Browse all available cores at:  
 > [https://buildbot.libretro.com/nightly/linux/x86_64/latest/](https://buildbot.libretro.com/nightly/linux/x86_64/latest/)
@@ -61,11 +61,11 @@ sudo mv ppsspp_libretro.info /usr/share/libretro/info/
 ---
-## Method 2 – Enable the Built‑in Core Downloader
+## Method 2: Enable the Built‑in Core Downloader
 If you prefer using RetroArch’s graphical interface to download cores, you can change the core directories to writable locations.
-### Step 1 – Edit RetroArch Configuration
+### Step 1: Edit RetroArch Configuration
 Create or edit `~/.config/retroarch/retroarch.cfg` and add these lines:
@@ -82,19 +82,19 @@ mkdir -p ~/.config/retroarch/libretro
 mkdir -p ~/.config/retroarch/libretro-info
 ```
-### Step 2 – Update Core Info Files
+### Step 2: Update Core Info Files
 - Launch RetroArch.
 - Go to **Online Updater** → **Update Core Info Files**.
 - Wait for the update to complete.
-### Step 3 – Download Cores
+### Step 3: Download Cores
 - Go to **Online Updater** → **Core Downloader**.
 - Select the core you want (e.g., PPSSPP).
 - The core will be downloaded to your user directory and will appear in the core list.
-> ⚠️ **Note:** Some cores may require additional system files (BIOS/assets). These are still placed in `~/.config/retroarch/system/` – you’ll need to obtain them separately (see below).
+> ⚠️ **Note:** Some cores may require additional system files (BIOS/assets). These are still placed in `~/.config/retroarch/system/`. You’ll need to obtain them separately (see below).
 ---
@@ -139,7 +139,7 @@ You can find many asset packs at:
 ## ROM / Game File Formats
 - **Supported formats** for PPSSPP: `.iso`, `.cso`, `.chd`, `.pbp`.
- **Always decompress your ROMs** – do not leave them in `.zip`, `.rar`, or `.7z` archives; the cores cannot read compressed archives directly.
+- **Always decompress your ROMs**: do not leave them in `.zip`, `.rar`, or `.7z` archives; the cores cannot read compressed archives directly.
 ---
@@ -151,13 +151,13 @@ You can find many asset packs at:
 | Core info files (GitHub) | [https://github.com/libretro/libretro-core-info](https://github.com/libretro/libretro-core-info) |
 | System assets (BIOS, firmware, etc.) | [https://buildbot.libretro.com/assets/system/](https://buildbot.libretro.com/assets/system/) |
 | Official RetroArch documentation | [https://docs.libretro.com/](https://docs.libretro.com/) |
-| Debian Wiki – RetroArch | [https://wiki.debian.org/RetroArch](https://wiki.debian.org/RetroArch) |
+| Debian Wiki: RetroArch | [https://wiki.debian.org/RetroArch](https://wiki.debian.org/RetroArch) |
 ---
 ## Final Notes
- The Debian package disables auto‑updates and the core downloader **by default** – this is intentional for stability.
+- The Debian package disables auto‑updates and the core downloader **by default**: this is intentional for stability.
 - Manual installation (Method 1) is the most straightforward and works for **any** core, regardless of distribution restrictions.
 - If you choose Method 2, remember that you may still need to manually place BIOS/asset files in `~/.config/retroarch/system/`.
 - Always test your video driver setting; `vulkan` is recommended for PPSSPP and other 3D‑heavy cores.
@@ -2,7 +2,7 @@
 ### 1. What does this component do?
-This module is responsible for the secure management of disk-based swap space within the `debianito` environment. Unlike standard Linux tools that might overwrite existing configurations or conflict with memory compression features (like ZRAM), this script operates as a **priority-aware, persistent swap manager**.
+This module manages disk-based swap space in the `debianito` environment. It leaves existing configuration alone and works alongside ZRAM instead of conflicting with it.
 Its primary functions include:
@@ -13,17 +13,17 @@ Its primary functions include:
 ### 2. How does it work?
-The script leverages several advanced Linux subsystems and safety protocols:
+The script uses several Linux subsystems and safety mechanisms:
-1. **File System Detection:** It identifies the filesystem type of the target partition (e.g., `ext4`, `btrfs`). For Btrfs, it applies specific flags (`chattr +C` for copy-on-write optimization) to prevent performance degradation during swap operations.
+1. **File System Detection:** It identifies the filesystem type of the target partition (e.g., `ext4`, `btrfs`). For Btrfs, it applies specific flags (`chattr +C` to disable copy-on-write) to avoid performance loss during swap operations.
 2. **Allocation Strategy:** It prefers `fallocate` for instant space reservation on supported filesystems, falling back to `dd if=/dev/zero` for compatibility or zeroing requirements (like Btrfs).
 3. **Fstab Validation:** Before writing changes to `/etc/fstab`, it creates a temporary file and validates the syntax using `findmnt --verify`. If validation fails, the script aborts and restores the original state.
-4. **Concurrency Control:** It utilizes `flock` on `/run/lock/debianito-swap.lock`. This ensures that if another process is modifying swap settings (e.g., a system update), this script will wait or exit gracefully to prevent filesystem corruption.
+4. **Concurrency Control:** It uses `flock` on `/run/lock/debianito-swap.lock`. If another process is modifying swap settings (e.g., a system update), this script waits or exits gracefully to prevent filesystem corruption.
 5. **Swappiness Tuning:** It configures `vm.swappiness` via both runtime (`sysctl -w`) and persistent (`/etc/sysctl.d/99-swappiness-debianito.conf`) mechanisms, defaulting to values that favor RAM usage over disk swapping (e.g., 10-20).
 ### 3. The Logical Decision Tree (Step by Step)
-The execution flow follows a strict logical tree designed for safety and idempotency:
+The execution flow runs in a fixed order and is safe to repeat:
 1. **Initialization & Locking:**
    * The `manage_swap()` function attempts to acquire an exclusive lock (`flock -n`). If the lock is held by another process, it immediately exits with a "Busy" message to prevent conflicts.
@@ -58,7 +58,7 @@ Each option in the swap management submenu serves a specific technical purpose:
 * **Option 1: Show current swap & swappiness**
  * **Technical Action:** Aggregates data from `/proc/swaps`, `/proc/sys/vm/swappiness`, and `/etc/fstab`.
-  * **Significance:** Provides an audit trail of the current memory management state. It verifies if ZRAM is active (implied by priority check) and how much disk swap is currently in use.
+  * **Significance:** Shows the current memory management state. It verifies if ZRAM is active (implied by priority check) and how much disk swap is currently in use.
 * **Option 2: Create / resize swapfile**
  * **Technical Action:** Allocates a new block device file (`/swapfile`) or expands an existing one. Sets the `pri=10` flag to ensure it acts as a secondary memory layer after ZRAM fills up.
@@ -70,7 +70,7 @@ Each option in the swap management submenu serves a specific technical purpose:
 * **Option 4: Change swappiness**
  * **Technical Action:** Modifies the kernel parameter `vm.swappiness`.
-  * **Significance:** Controls the "aggressiveness" of swapping. A lower value (e.g., 10) tells the kernel to keep data in RAM longer, only using swap as a last resort. This is critical for desktop performance and battery life on laptops.
+  * **Significance:** Controls the "aggressiveness" of swapping. A lower value (e.g., 10) tells the kernel to keep data in RAM longer, only using swap as a last resort. This matters for desktop performance and battery life on laptops.
 * **Option 5: Back to main menu**
  * **Technical Action:** Releases the file lock (`exec 9>&-`) and terminates the submenu loop.
@@ -2,20 +2,20 @@
 ### 1. What Does This Component Do?
-This component serves as the **System Abstraction Layer** and diagnostic engine of the Debianito script. It is not merely a display utility; it acts as the foundational state initializer for the other menu options. Its primary function is to perform pre-flight hardware enumeration, OS validation, and environment checks in "cold" mode (before any configuration changes are made).
+This component performs the hardware enumeration, OS validation and environment checks that the rest of the script builds on. It runs in "cold" mode, before any configuration change is made, and the other menu options read the state it initializes instead of re-detecting everything.
 **Initialization** (boot checks in `debianito.sh`, hardware state on demand via `_ensure_state_detected`):
-1. **Dependency auto-install**: The script checks for `whiptail` and `lsb-release`, installing them automatically if missing — ensuring the TUI and version detection work on minimal systems.
+1. **Dependency auto-install**: The script checks for `whiptail` and `lsb-release`, installing them automatically if missing, so the TUI and version detection work on minimal systems.
-2. **`lspci` guard and cache**: `command -v lspci &>/dev/null` validates availability before execution. If present, the full `lspci -nn` output is captured once into the global variable `LSPCI_OUTPUT`. All subsequent GPU, Ethernet, and network detection reads from this cache — avoiding redundant `lspci` invocations and ensuring consistent data throughout the session.
+2. **`lspci` guard and cache**: `command -v lspci &>/dev/null` validates availability before execution. If present, the full `lspci -nn` output is captured once into the global variable `LSPCI_OUTPUT`. All subsequent GPU, Ethernet, and network detection reads from this cache, avoiding redundant `lspci` invocations and keeping the data consistent throughout the session.
-3. **APT update deduplication**: The helper `_ensure_apt_updated` prevents redundant `apt update` calls by tracking whether the package lists have been refreshed recently. This is critical for performance when multiple modules (repos, firmware, GPU, kernel) each need to verify repository state.
+3. **APT update deduplication**: The helper `_ensure_apt_updated` prevents redundant `apt update` calls by tracking whether the package lists have been refreshed recently. This matters for performance when multiple modules (repos, firmware, GPU, kernel) each need to verify repository state.
 4. **State refresh flag**: `STATE_REFRESHED=true` is set before `;;` in every `case` branch of the main menu loop, ensuring that each menu entry starts with a clean, consistent state rather than stale cached data.
-By populating global variables such as `DEBIAN_VERSION`, `GPU_TYPE`, `CPU_SUMMARY`, and network interface states, it ensures that the subsequent menu options have access to accurate context. This prevents the user from making blind decisions—for example, attempting to install proprietary drivers on a system without detected hardware or selecting repositories incompatible with the current Debian codename. It transforms raw kernel data into actionable configuration parameters.
+The variables it populates (`DEBIAN_VERSION`, `GPU_TYPE`, `CPU_SUMMARY`, network interface states) give the later menu options real context, so the user is not asked to make blind decisions: installing proprietary drivers on hardware that is not there, or selecting repositories that do not match the current Debian codename.
 ### 2. System Commands Used (Technical Mapping)
-The following table details the native Linux tools and file descriptors utilized by `utils.sh` to extract specific diagnostic data points. This mapping demonstrates reliance on standard, non-intrusive system utilities rather than proprietary binaries.
+The table below maps each piece of diagnostic data to the standard Linux tool `utils.sh` reads it from; none of it needs proprietary binaries.
 | Feature | Command / Tool | Technical Purpose & Logic |
 | :--- | :--- | :--- |
@@ -28,15 +28,15 @@ The following table details the native Linux tools and file descriptors utilized
 | **Storage** | `lsblk -d -o NAME,SIZE,ROTA` | Distinguishes between NVMe (`nvme`), SSD (RoT=0), and HDD (RoT=1) to provide storage topology summary. |
 | **Display Server** | Environment Vars (`XDG_SESSION_TYPE`) | Checks `WAYLAND_DISPLAY` vs `DISPLAY` variables to determine if the system is running Wayland, X11, or TTY. |
-### 3. Strategic Importance for the Script
+### 3. Why Detection Matters
-This diagnostic phase is vital for engineering stability and user experience (UX) integrity within the script architecture:
+Each check protects a different part of the script:
 * **Context-Aware Configuration:** The detection of `HAS_NVIDIA`, `HAS_AMD`, or `HAS_INTEL` directly dictates which sub-modules are loaded in `debianito.sh`. If no GPU is detected, graphics driver menus are skipped. This prevents "false positive" installation prompts that confuse the user.
 * **Repository Compatibility Guardrails:** The `detect_debian_version` function validates the OS against supported codenames (11, 12, 13). It specifically triggers Bullseye-specific logic (`configure_repos_bullseye`) only when necessary, preventing repository errors on newer or older distributions.
 * **APT Update Deduplication:** The `_ensure_apt_updated` helper tracks whether `apt update` has been run recently. Multiple modules (repos, firmware, GPU, kernel) share a single update cycle, preventing redundant network calls and inconsistent package state between modules.
 * **State Refresh Consistency:** `STATE_REFRESHED=true` is set before `;;` in every `case` branch of the main menu loop, ensuring each menu entry starts with a clean state and preventing stale variable propagation between sequential selections.
-* **Time Synchronization Safety:** The `check_system_time` function prevents package installation failures caused by clock skew (which breaks GPG signatures in APT). By offering an automated NTP sync before proceeding, it ensures the integrity of the entire software supply chain within the script.
+* **Time Synchronization Safety:** The `check_system_time` function prevents package installation failures caused by clock skew, which breaks APT's GPG signatures. It offers an automated NTP sync before proceeding so the signatures verify again.
 * **Root/Sudo Enforcement:** Early execution of `check_root` and `check_sudo` enforces security best practices. It prevents accidental privilege escalation or silent failures that often occur when scripts run with incorrect permissions.
 ### 4. Formatting and UX in the Terminal
@@ -46,4 +46,4 @@ The raw data collected by these functions is processed into a human-readable for
 * **Structured String Assembly:** Functions like `_show_sysinfo` build multi-line strings (`msg+="...")`, appending newlines and conditional logic. This ensures that if multiple GPUs are found, they are listed sequentially with drivers identified below each entry.
 * **Visual Hierarchy:** The data is organized into logical blocks (OS, Hardware, GPU, Network) with clear separators (`───`). This allows the user to quickly scan specific subsystems without scrolling through a monolithic log.
 * **Conditional Rendering:** The script checks for command availability (e.g., `if ! command -v lspci &>/dev/null` guards GPU detection, `if ! command -v ip &>/dev/null` guards network data). If tools are missing, it gracefully degrades to a warning message rather than crashing the TUI. When `lspci` is present, its output is cached in `LSPCI_OUTPUT` for all subsequent detection calls.
-* **TUI Integration:** The final formatted string is passed to `_msg`, which wraps the output in a `whiptail --msgbox`. This ensures the diagnostic information appears as a modal dialog with consistent dimensions and styling (colors defined globally in `debianito.sh`), maintaining a professional look regardless of the underlying terminal emulator.
+* **TUI Integration:** The final formatted string is passed to `_msg`, which wraps the output in a `whiptail --msgbox`. This makes the diagnostic information appear as a modal dialog with consistent dimensions and styling (colors defined globally in `debianito.sh`), regardless of the underlying terminal emulator.
@@ -2,7 +2,7 @@
 ## 1. What Does This Component Do?
-The **System Preferences** module (`modules/system/system_prefs.sh` + `modules/system/audio.sh`) consolidates first-boot personalization into a single menu. It is the only place in Debianito where **locale, timezone, and audio** are configured together — settings that Debian's installer often leaves at generic defaults and that affect every subsequent module.
+The **System Preferences** module (`modules/system/system_prefs.sh` + `modules/system/audio.sh`) consolidates first-boot personalization into a single menu. It is the only place in Debianito where locale, timezone and audio are configured together, settings that Debian's installer often leaves at generic defaults and that affect every subsequent module.
 It groups three independent preference domains behind one entry point:
@@ -12,7 +12,7 @@ It groups three independent preference domains behind one entry point:
 | **Language, Locales & Keyboard** | `system_prefs.sh:_prefs_locale_keyboard` | `locales`, `keyboard-configuration` |
 | **Audio & Sound Stack** | `system/audio.sh:_prefs_audio_menu` | PipeWire, ALSA, pavucontrol, pulsemixer, playerctl |
-The menu itself is `_system_preferences_menu` in `system_prefs.sh` — a simple `while true` loop with `whiptail --menu`:
+The menu itself is `_system_preferences_menu` in `system_prefs.sh`, a simple `while true` loop with `whiptail --menu`:
 ```
 1  Date, Time & Timezone
@@ -40,7 +40,7 @@ Timezone: America/Santiago
 **What it does technically:**
 1. Prints the current date/time (`date '+%Y-%m-%d %H:%M'`) and timezone (`timedatectl show -p Timezone --value`).
-2. Prompts via `_confirm "Timezone"` to run `sudo dpkg-reconfigure tzdata` — the Debian-standard interactive timezone selector (ncurses).
+2. Prompts via `_confirm "Timezone"` to run `sudo dpkg-reconfigure tzdata`, the Debian-standard interactive timezone selector (ncurses).
 3. Calls `_ensure_time_synced` from `utils.sh` regardless of the answer:
   - Forces `timedatectl set-ntp true`
   - Validates the timezone is not `n/a` or `Etc/UTC`; if it is and a display is available, opens `tzdata` again
@@ -62,12 +62,12 @@ sudo dpkg-reconfigure keyboard-configuration
 **What it does technically:**
- **`dpkg-reconfigure locales`** — Opens the Debian locales selector (e.g., `en_US.UTF-8`, `es_CL.UTF-8`). Generates the selected locales via `locale-gen` and updates `/etc/default/locale`. No reboot is required, but a re-login is needed for the new `LANG` to take effect.
+- **`dpkg-reconfigure locales`**: Opens the Debian locales selector (e.g., `en_US.UTF-8`, `es_CL.UTF-8`). Generates the selected locales via `locale-gen` and updates `/etc/default/locale`. No reboot is required, but a re-login is needed for the new `LANG` to take effect.
- **`dpkg-reconfigure keyboard-configuration`** — Configures `/etc/default/keyboard` (`XKBMODEL`, `XKBLAYOUT`, `XKBVARIANT`, `XKBOPTIONS`) and, on console, the keymap via `setupcon`. This affects both X11/Wayland and TTY.
+- **`dpkg-reconfigure keyboard-configuration`**: Configures `/etc/default/keyboard` (`XKBMODEL`, `XKBLAYOUT`, `XKBVARIANT`, `XKBOPTIONS`) and, on console, the keymap via `setupcon`. This affects both X11/Wayland and TTY.
 Both commands are run with `env LC_ALL=C LANGUAGE=C` to guarantee the debconf dialogs render in English even when the current locale is broken.
-This option has **no detection logic** — it delegates entirely to Debian's standard tools. It is idempotent and safe to run repeatedly.
+This option has **no detection logic**: it delegates entirely to Debian's standard tools. It is idempotent and safe to run repeatedly.
 ---
@@ -91,7 +91,7 @@ items+=("playerctl"      "Multimedia key controller (playerctl)" $state)
 ```
 - **`_state <pkg>`** (in `utils.sh`) returns `ON` if `dpkg -l <pkg>` shows `^ii`, otherwise `OFF`.
- **`_is_headless`** returns true when both `$DISPLAY` and `$WAYLAND_DISPLAY` are empty — in that case `pavucontrol` is hidden because it requires a GUI.
+- **`_is_headless`** returns true when both `$DISPLAY` and `$WAYLAND_DISPLAY` are empty; in that case `pavucontrol` is hidden because it requires a GUI.
 - Package name for PipeWire varies by Debian version:
  - Debian 11 Bullseye → `pipewire` (the `pipewire-audio` metapackage does not exist)
  - Debian 12/13 → `pipewire-audio`
@@ -100,7 +100,7 @@ The checklist is shown via `whiptail --checklist` with the title **"Audio & Soun
 #### 4.2 PipeWire Installation Logic: `_install_pipewire_standard`
-This function handles the **PipeWire Audio Stack with Bluetooth Hi-Res codecs** — the core of modern Linux audio.
+This function handles the **PipeWire Audio Stack with Bluetooth Hi-Res codecs**.
 **Codec package resolution:**
@@ -147,7 +147,7 @@ systemctl --user restart wireplumber pipewire pipewire-pulse
 | --------- | --------- | --------------- |
 | `alsa-utils` + `alsa-ucm-conf` | ALSA CLI tools (`aplay`, `amixer`, `alsamixer`) and UCM configs for modern sound cards | `is_installed alsa-utils` |
 | `pavucontrol` | GTK GUI volume control (PulseAudio/PipeWire compatible). Hidden in headless mode. | `is_installed pavucontrol` |
-| `pulsemixer` | Terminal (ncurses) mixer — works in TTY and headless | `is_installed pulsemixer` |
+| `pulsemixer` | Terminal (ncurses) mixer, works in TTY and headless | `is_installed pulsemixer` |
 | `playerctl` | MPRIS CLI to control media players via keyboard shortcuts | `is_installed playerctl` |
 Each package is installed via `_run_install <pkg>` which confirms the version via `apt-cache policy` before installing.
@@ -188,10 +188,10 @@ Each package is installed via `_run_install <pkg>` which confirms the version vi
 ## 6. Integration with Other Modules
- **Firmware (`firmware.sh`)** — Bluetooth firmware packages (`firmware-iwlwifi`, etc.) are separate from the Bluetooth *stack* (`bluez`). This menu complements firmware by ensuring the audio side of Bluetooth (PipeWire codecs) is ready.
+- **Firmware (`firmware.sh`)**: Bluetooth firmware packages (`firmware-iwlwifi`, etc.) are separate from the Bluetooth *stack* (`bluez`). This menu complements firmware by ensuring the audio side of Bluetooth (PipeWire codecs) is ready.
- **Desktop & Display (`desktop_display.sh`)** — XFCE/LXDE installations often need audio configured afterwards. Running System Preferences → Audio after a new desktop ensures the correct mixer is available.
+- **Desktop & Display (`desktop_display.sh`)**: New desktop installations (XFCE, LXDE, GNOME or KDE Plasma) often need audio configured afterwards. Running System Preferences → Audio after a new desktop ensures the correct mixer is available.
- **Gaming (`gaming.sh`)** — Many games require PipeWire/PulseAudio for voice chat. The gaming module assumes audio is already functional.
+- **Gaming (`gaming.sh`)**: Many games require PipeWire/PulseAudio for voice chat. The gaming module assumes audio is already functional.
- **Time sync (`utils.sh:_ensure_time_synced`)** — Also called automatically before the first `apt update`. This menu is the manual override.
+- **Time sync (`utils.sh:_ensure_time_synced`)**: Also called automatically before the first `apt update`. This menu is the manual override.
 ---
@@ -210,7 +210,7 @@ Each package is installed via `_run_install <pkg>` which confirms the version vi
 ## References
- [Debian TimeZone Config — wiki.debian.org/TimeZoneChanges](https://wiki.debian.org/TimeZoneChanges)
+- [Debian TimeZone Config: wiki.debian.org/TimeZoneChanges](https://wiki.debian.org/TimeZoneChanges)
- [Debian Locales — wiki.debian.org/Locale](https://wiki.debian.org/Locale)
+- [Debian Locales: wiki.debian.org/Locale](https://wiki.debian.org/Locale)
- [PipeWire — wiki.debian.org/PipeWire](https://wiki.debian.org/PipeWire)
+- [PipeWire: wiki.debian.org/PipeWire](https://wiki.debian.org/PipeWire)
- [PipeWire Bluetooth Codecs — GitLab PipeWire wiki](https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/FAQ#bluetooth)
+- [PipeWire Bluetooth Codecs: GitLab PipeWire wiki](https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/FAQ#bluetooth)
@@ -2,9 +2,9 @@
 ### 1. What does this component do?
-This component serves as a centralized utility suite designed to streamline administrative access, enhance usability during system maintenance, and correct common permission inconsistencies found in fresh Debian installations or environments where `sudo` usage has been mishandled. It acts as an automated "First-Time User" setup tool that bridges the gap between strict Linux security policies (where standard users cannot modify system files) and practical daily workflow needs (such as installing software without constant password prompts).
+This module prepares a normal user account for day-to-day administration on a fresh Debian installation, or on one where `sudo` usage has been mishandled. Debian gives a standard user no administrative rights by default, so routine work such as installing software would ask for a password each time; this menu closes that gap and fixes the ownership and feedback annoyances that come with fresh setups.
-At a high level, it manages four critical aspects of user privilege:
+It manages four aspects of user privileges:
 1. **Elevated Permissions:** Ensures the current user has membership in the `sudo` group.
 2. **Workflow Efficiency:** Configures specific commands to run without authentication (NOPASSWD) for maintenance tasks.
@@ -13,7 +13,7 @@ At a high level, it manages four critical aspects of user privilege:
 ### 2. What exactly does it do and why
-The script executes a sub-menu loop that allows the user to toggle between four distinct configurations. Each option addresses a specific pain point in Linux administration:
+The script executes a sub-menu loop that allows the user to toggle between four distinct configurations. Each option fixes a specific annoyance in Linux administration:
 * **Sudo Group Membership (Option 1):**
  * **Action:** Checks if the current username exists within the `/etc/group` file under the `sudo` group entry. If absent, it adds the user via `usermod -aG sudo`.
@@ -83,13 +83,13 @@ The execution flow is governed by `sudo_config.sh`, which acts as a state machin
    * *On Confirm:* Write `Defaults pwfeedback` to `/etc/sudoers.d/pwfeedback`.
 * **Step B:** Verify write permission. If successful, notify success; otherwise, log error and return status 1.
-### 4. Compatibility with all Debian
+### 4. Compatibility Across Debian Versions
-This module is designed for universal compatibility across the Debian family (Bullseye, Bookworm, Trixie, etc.) due to its reliance on standard POSIX-compliant tools and strict path handling.
+The module works across the Debian family (Bullseye, Bookworm, Trixie) because it only uses standard POSIX tools and handles paths strictly.
-* **Architecture Independence:** The script utilizes `usermod`, `chown`, and `grep` which are available on all x86_64, arm64, and i386 Debian architectures.
+* **Architecture Independence:** The script uses `usermod`, `chown`, and `grep`, which are available on all x86_64, arm64, and i386 Debian architectures.
-* **Version Agnosticism (Debian 11+):**
+* **Version Independence (Debian 11+):**
  * **Sudoers Syntax:** The script writes to `/etc/sudoers.d/`, a directory introduced in `sudo` version 1.9.0p5 (available since Debian 7). It avoids editing the master file (`/etc/sudoers`) directly, preventing lockfile issues and syntax errors regardless of the specific Debian version's sudo configuration style.
  * **Path Hardening:** The NOPASSWD logic explicitly includes both `/usr/bin` and `/bin` paths for commands like `apt`. This ensures that on older Debian versions (e.g., Bullseye) where binaries might reside in different locations or symlinks differ, the permissions remain valid.
 * **Security Best Practices:** By isolating configurations into separate files (`/etc/sudoers.d/`) and setting restrictive permissions (`0440`), it adheres to Debian's security guidelines for `sudo`. This ensures that even on older systems with stricter default policies, the configuration is accepted without requiring a full system reboot or sudo upgrade.
-* **Importance:** Consistent behavior across versions means users can migrate between Debian releases (e.g., from 11 to 12) without needing to manually reconfigure these specific privileges, ensuring a stable and secure environment regardless of the underlying OS version.
+* **Importance:** Users can move between Debian releases (e.g., from 11 to 12) without reconfiguring these privileges by hand.
@@ -1,10 +1,10 @@
 # Option 9: ZRAM Configuration & Memory Optimization
-## 1. The Science of ZRAM vs. Traditional Swap
+## 1. ZRAM vs. Traditional Swap
 ### Core Concept: CPU Cycles vs. Disk I/O
-Traditional swap storage operates on a fundamental latency gap that becomes critical under memory pressure:
+Traditional swap has a latency gap that matters under memory pressure:
 | Storage Medium | Latency Range | Write Amplification | SSD Wear Impact |
 | --------------- | --------------- | --------------------- | ----------------- |
@@ -27,19 +27,19 @@ ZRAM creates a compressed block device entirely within physical memory. When pag
 2. **Stored in RAM pool** at compressed size (typically 2:1 to 3:1 ratio)
 3. **Decompressed instantly** when needed (microseconds vs milliseconds)
-The trade-off is explicit: **CPU cycles for reduced I/O latency**. Modern CPUs can compress/decompress pages in microseconds, making this far cheaper than any disk operation.
+The trade is CPU cycles for less I/O latency. Modern CPUs compress and decompress pages in microseconds, which is far cheaper than any disk operation.
 ### Why Only LZ4 and ZSTD?
-The script offers only two algorithms because they represent the optimal balance points:
+The script offers only two algorithms because they hit the best balance of speed and ratio:
 | Algorithm | Compression Ratio | Speed | CPU Overhead | Best Use Case |
 |-----------|------------------|-------|--------------|---------------|
 | **LZ4**   | ~2:1–3:1         | Fastest | Lowest | Gaming, real-time workloads |
 | **ZSTD**  | ~3:1–5:1         | Medium | Moderate | General use, better memory savings |
- **LZ4**: Prioritizes speed over compression ratio. Ideal for systems where CPU availability is limited or latency-sensitive (gaming servers).
+- **LZ4**: Prioritizes speed over compression ratio. Best when CPU is limited or latency matters (gaming servers).
- **ZSTD**: Offers superior compression ratios with acceptable overhead. Best for systems prioritizing maximum effective RAM capacity.
+- **ZSTD**: Compresses more at acceptable overhead. Best when the goal is maximum effective RAM.
 The kernel supports additional algorithms (lzo-rle, deflate, lz4hc), but these are either deprecated, slower, or offer diminishing returns compared to LZ4/ZSTD in modern hardware.
@@ -49,7 +49,7 @@ By intercepting swap writes before they reach physical storage:
 - **Write Reduction**: Pages that would write to disk now compress in RAM
 - **TBW Conservation**: Each avoided write preserves P/E cycles on NAND flash cells
- **System Longevity**: Critical for systems with limited SSD endurance ratings (e.g., 100 TBW consumer drives)
+- **System Longevity**: Matters for systems with limited SSD endurance (e.g., 100 TBW consumer drives)
 As the Linux kernel documentation states: *"Users with SSDs as swap devices can extend device lifespan by drastically reducing writes that shorten its life."*
@@ -59,7 +59,7 @@ As the Linux kernel documentation states: *"Users with SSDs as swap devices can
 ### Pipeline Execution Sequence
-The script follows a deterministic flow to ensure safe, reproducible configuration:
+The script follows a fixed sequence:
 ```
 ┌─────────────────────────────────────────────────────────────┐
@@ -107,7 +107,7 @@ The script follows a deterministic flow to ensure safe, reproducible configurati
 └─────────────────────────────────────────────────────────────┘
 ```
-### Mathematical Size Calculation
+### Size Formula
 The script uses this formula to determine ZRAM size:
@@ -126,7 +126,7 @@ fi
 - `/ 1024 / 1024`: Convert KB to GB
 - `+ 1`: Add rounding buffer for odd values
 - **≤8 GB**: Target 50% of total RAM (generous swap for low-memory systems)
- **>8 GB**: Fixed 4096 MB — avoids excessive RAM reservation on high-memory machines while still providing meaningful swap space
+- **>8 GB**: Fixed 4096 MB, which avoids excessive RAM reservation on high-memory machines while still providing meaningful swap space
 **Examples:**
@@ -168,20 +168,20 @@ This prevents thrashing where pages bounce between slow disk swap and fast RAM-b
 ### How ZRAM Coexists with Disk Swap
-The script does **not** hardcode `vm.swappiness` or watermark tuning. Instead, it uses a **priority-based swap hierarchy** combined with an explicit swappiness control in the Swap module:
+The script does **not** hardcode `vm.swappiness` or watermark tuning. It uses a priority-based swap hierarchy combined with explicit swappiness control in the Swap module:
 | Swap Device | Priority | Config Location | When It Is Used |
 |-------------|----------|-----------------|-----------------|
-| **ZRAM** | `100` | `/etc/default/zramswap` (`PRIORITY=100`) | **First** — kernel prefers higher priority |
+| **ZRAM** | `100` | `/etc/default/zramswap` (`PRIORITY=100`) | **First**: kernel prefers higher priority |
-| **Disk swapfile** (`/swapfile`) | `10` | `/etc/fstab` (`pri=10`) + `# debianito-managed-swap` tag | **Second** — only after ZRAM device is full |
+| **Disk swapfile** (`/swapfile`) | `10` | `/etc/fstab` (`pri=10`) + `# debianito-managed-swap` tag | **Second**: only after ZRAM device is full |
 This is implemented in `zram.sh:_zram_create` (writes `PRIORITY=100`) and `swap.sh:_swap_create_file` (writes `pri=10`). Priority is the canonical Linux `swapon` mechanism: `swapon --show` lists `PRIO` and the kernel always fills the highest-priority device first.
 ### Swappiness Is Managed Separately
-Swappiness (`vm.swappiness`, 0–100, default 60 on Debian) controls **how eagerly the kernel swaps at all**, regardless of which device is preferred.
+Swappiness (`vm.swappiness`, 0–100, default 60 on Debian) controls how eagerly the kernel swaps at all, regardless of which device is preferred.
- The ZRAM module **does not change swappiness**. Changing it would affect both ZRAM and disk swap in ways that are workload-specific.
+- The ZRAM module does not change swappiness. Changing it would affect both ZRAM and disk swap in ways that are workload-specific.
 - To tune it, use **Option 10 → Swap Management → 4. Change swappiness** (`swap.sh:_swap_set_swappiness`):
  ```bash
@@ -194,10 +194,10 @@ Swappiness (`vm.swappiness`, 0–100, default 60 on Debian) controls **how eager
 - Recommended starting points (not enforced by the script):
  - **General desktop**: `60` (Debian default)
-  - **Gaming / 8 GB or less**: `80–100` — allows ZRAM to be used earlier, trading CPU for reduced disk I/O
+  - **Gaming / 8 GB or less**: `80–100`, which allows ZRAM to be used earlier, trading CPU for reduced disk I/O
  - **ZRAM-only, no disk swap**: `100–150` is safe because swap *is* RAM (compressed); there is no SSD wear cost
-> **Previous documentation** recommended `vm.swappiness = 180` plus `watermark_*` and `page-cluster` tuning for ZRAM. Those values are **not written by the current script** and are omitted here to avoid drifting from the implemented behavior. If you need watermark tuning, add it manually to `/etc/sysctl.d/` and validate with your workload.
+> **Previous documentation** recommended `vm.swappiness = 180` plus `watermark_*` and `page-cluster` tuning for ZRAM. The current script does not write those values; they are omitted here so this document matches the implementation. If you need watermark tuning, add it manually to `/etc/sysctl.d/` and validate with your workload.
 ### Verifying the Hierarchy
@@ -280,7 +280,7 @@ watch -n 5 'free -h && zramctl'
 ### Permanent Configuration
-To ensure ZRAM persists across reboots, the script writes configuration to `/etc/default/zramswap`. This file is read by systemd's `zramswap.service` unit at boot time. Additionally, adding the following ensures the kernel module loads:
+To ensure ZRAM persists across reboots, the script writes configuration to `/etc/default/zramswap`. This file is read by systemd's `zramswap.service` unit at boot time. The following also loads the kernel module:
 ```bash
 echo "zram" | sudo tee /etc/modules-load.d/zram.conf
@@ -1,185 +0,0 @@
 #!/usr/bin/env bash
 # audio.sh — Audio & Sound (PipeWire, ALSA, PulseAudio tools)
 _cat_audio() {
    local headless=false
    _is_headless && headless=true
    local -a items=()
    local pw_label="PipeWire Audio Stack (Bluetooth Hi-Res)"
    local pw_state; pw_state=$(_state "pipewire-audio")
    items+=(
        "pipewire-audio" "$pw_label" "$pw_state"
    )
    local alsa_state; alsa_state=$(_state "alsa-utils")
    items+=(
        "alsa-utils" "ALSA Utilities (alsa-utils, alsa-ucm-conf)" "$alsa_state"
    )
    if ! $headless; then
        local pavu_state; pavu_state=$(_state "pavucontrol")
        items+=(
            "pavucontrol" "Volume Control GUI (pavucontrol)" "$pavu_state"
        )
    fi
    local pulsemixer_state; pulsemixer_state=$(_state "pulsemixer")
    local playerctl_state;  playerctl_state=$(_state "playerctl")
    items+=(
        "pulsemixer" "Terminal audio mixer (pulsemixer)" "$pulsemixer_state"
        "playerctl"  "Multimedia key controller (playerctl)" "$playerctl_state"
    )
    local item_count=${#items[@]}
    local lista_alto=$((item_count > TUI_ALTO_LISTA ? TUI_ALTO_LISTA : item_count))
    local choices
    choices=$(_checklist "Audio & Sound" "Check [*] the packages you want installed.\n" \
        $TUI_ALTO $TUI_ANCHO $lista_alto "${items[@]}")
    clear
    [ -z "$choices" ] && return
    local cleaned; cleaned=$(echo "$choices" | tr -d '"')
    for pkg in $cleaned; do
        case $pkg in
            pipewire-audio) _install_pipewire_standard ;;
            alsa-utils)
                if ! is_installed "alsa-utils"; then
                    _run_install "alsa-utils alsa-ucm-conf"
                else
                    echo "alsa-utils already installed."
                fi
                ;;
            pavucontrol)
                if ! is_installed "pavucontrol"; then
                    _run_install "pavucontrol"
                else
                    echo "pavucontrol already installed."
                fi
                ;;
            pulsemixer)
                if ! is_installed "pulsemixer"; then
                    _run_install "pulsemixer"
                else
                    echo "pulsemixer already installed."
                fi
                ;;
            playerctl)
                if ! is_installed "playerctl"; then
                    _run_install "playerctl"
                else
                    echo "playerctl already installed."
                fi
                ;;
        esac
    done
    echo -e "${GREEN}Audio & Sound setup complete.${NC}"
 }
 _install_pipewire_standard() {
    local bt_pkgs="libldacbt-abr2 libldacbt-enc2 libopenaptx0 libspa-0.2-bluetooth"
    if apt-cache show libfdk-aac2t64 &>/dev/null; then
        bt_pkgs+=" libfdk-aac2t64"
    elif apt-cache show libfdk-aac2 &>/dev/null; then
        bt_pkgs+=" libfdk-aac2"
    fi
    # ── Resolve versions (needed for both installed and not-installed branches) ──
    local stable_ver=""
    stable_ver=$(apt-cache policy pipewire-audio 2>/dev/null | awk 'NR==3 {print $2; exit}') || true
    local bpo_ver=""
    if [ "$DEBIAN_VERSION" = "13" ] && [ "$(is_backports_enabled)" = "true" ]; then
        bpo_ver=$(apt-cache madison pipewire-audio 2>/dev/null | \
            grep "${DEBIAN_CODENAME}-backports" | awk '{print $3}' | head -1) || true
    fi
    local pkg_check="pipewire-audio"
    [ "$DEBIAN_VERSION" = "11" ] && pkg_check="pipewire"
    # ── Already installed branch ──
    if is_installed "$pkg_check"; then
        if [ -n "$bpo_ver" ]; then
            local current_ver
            current_ver=$(dpkg -l "$pkg_check" 2>/dev/null | awk '/^ii/{print $3}') || true
            if _confirm "PipeWire" \
                "PipeWire ${current_ver:+v${current_ver} }already installed.\n\nUpgrade to backports version v${bpo_ver}?"; then
                echo "Upgrading PipeWire Audio Stack..."
                echo "-> Target version: v${bpo_ver} (from ${DEBIAN_CODENAME}-backports)"
                echo "-> Including Bluetooth Hi-Res codecs (LDAC, aptX, AAC)"
                _run_cmd "PipeWire" \
                    "sudo apt install -y --reinstall -t ${DEBIAN_CODENAME}-backports pipewire-audio $bt_pkgs" \
                    "Upgrading PipeWire from backports..."
                if [ "$DEBIAN_VERSION" != "11" ]; then
                    echo "Restarting PipeWire services..."
                    systemctl --user restart wireplumber pipewire pipewire-pulse 2>/dev/null || true
                    echo -e "${GREEN}PipeWire services restarted.${NC}"
                fi
                return
            fi
        fi
        echo "$pkg_check already installed."
        return
    fi
    # ── Confirm dialog ──
    local apt_target="" pw_ver="" pw_src=""
    if [ -n "$bpo_ver" ]; then
        local msg="Backports repository is enabled.\n\n"
        msg+="Available versions:\n"
        msg+="  - Stable:   v${stable_ver:-unknown}\n"
        msg+="  - Backports: v${bpo_ver}\n\n"
        msg+="Install from Backports (Recommended for newer hardware)\nor from Stable (more conservative)?"
        if _confirm_custom "PipeWire Install" "$msg" "Backports" "Stable" 14 70; then
            apt_target="-t ${DEBIAN_CODENAME}-backports"
            pw_ver="$bpo_ver"
            pw_src="from ${DEBIAN_CODENAME}-backports"
        else
            pw_ver="$stable_ver"
        fi
    else
        local msg="PipeWire Audio Stack (v${stable_ver:-unknown})\n"
        msg+="will be installed along with Bluetooth Hi-Res\n"
        msg+="codecs (LDAC, aptX, AAC).\n\n"
        msg+="Continue with installation?"
        if ! _confirm "PipeWire Install" "$msg" 12 65; then
            echo "PipeWire installation cancelled."
            return
        fi
        pw_ver="$stable_ver"
    fi
    echo "Installing PipeWire Audio Stack..."
    echo "-> Detected version: ${pw_ver:-unknown} ${pw_src:+($pw_src)}"
    echo "-> Including Bluetooth Hi-Res codecs (LDAC, aptX, AAC)"
    case "$DEBIAN_VERSION" in
        11)
            _run_cmd "PipeWire" \
                "sudo apt install -y pipewire libspa-0.2-bluetooth pipewire-alsa libspa-0.2-jack $bt_pkgs" \
                "Installing PipeWire (Bullseye basic mode)..."
            echo -e "${GREEN}PipeWire installed (Bullseye basic mode).${NC}"
            ;;
        12)
            _run_cmd "PipeWire" \
                "sudo apt install -y pipewire-audio $bt_pkgs" \
                "Installing pipewire-audio meta-package (Bookworm)..."
            echo -e "${GREEN}PipeWire audio stack installed.${NC}"
            ;;
        13)
            _run_cmd "PipeWire" \
                "sudo apt install -y $apt_target pipewire-audio $bt_pkgs" \
                "Installing pipewire-audio meta-package (Trixie)..."
            echo -e "${GREEN}PipeWire audio stack installed.${NC}"
            ;;
    esac
    if [ "$DEBIAN_VERSION" != "11" ]; then
        echo "Restarting PipeWire services..."
        systemctl --user restart wireplumber pipewire pipewire-pulse 2>/dev/null || true
        echo -e "${GREEN}PipeWire services restarted.${NC}"
    fi
 }
@@ -111,6 +111,15 @@ _write_classic_branch() {
 }
 _branch_migration() {
    # Unattended guard: branch migration is the one operation
    # that can leave the system unbootable, so --yes alone is
    # not enough — it also requires --allow-destructive even
    # when every other prompt auto-accepts.
    if [ "${AUTO_YES:-0}" = "1" ] && [ "${ALLOW_DESTRUCTIVE:-0}" != "1" ]; then
        echo "Branch migration is destructive. Re-run with --allow-destructive, or drop --yes to confirm interactively." >&2
        return 1
    fi
    # ── Screen 1: Risk warning ──
    _msg_red "WARNING: Branch Migration" \
        "Migrating from Debian Stable to Testing or SID is a\n\
@@ -647,6 +647,9 @@ install_backports_or_stable() {
 # ----------------------------------------------------------------------
 _confirm() {
    # --yes (unattended mode): auto-accept without
    # invoking whiptail; the prompt gate is the flag itself.
    [ "${AUTO_YES:-0}" = "1" ] && return 0
    whiptail --title "$1" --yes-button "Yes" --no-button "No" \
        --yesno "$2" "${3:-10}" "${4:-65}"
 }
@@ -711,6 +714,7 @@ _validate_sudoers() {
    rm -f "$tmpfile"
 }
 # shellcheck disable=SC2120  # Optional prompt arg used by GPU modules.
 _pause() {
    local msg="${1:-Press Enter to continue...}"
    echo -e "$msg"
@@ -867,6 +871,7 @@ _detect_lang_pkg() {
 # ----------------------------------
 # Network connectivity check
 # ----------------------------------
 # shellcheck disable=SC2120  # Optional probe target (default: deb.debian.org).
 _check_network() {
    local target="${1:-deb.debian.org}"
@@ -352,6 +352,11 @@ mock_reset() {
    export MOCK_WHIPTAIL_OUTPUT=""
    export MOCK_WHIPTAIL_RC="0"
    # CLI flags (debianito.sh parser) — reset so unattended
    # mode never leaks between tests.
    export AUTO_YES=0
    export ALLOW_DESTRUCTIVE=0
    # sudo(8)
    export MOCK_SUDO_DRY_RUN="0"
    export MOCK_SUDO_LOG="$(mktemp)"
@@ -144,3 +144,34 @@ wlan0 10.0.0.5/24"
    [ "${ETH_NAMES[0]}" = "eth0" ]
    [ "${WIFI_NAMES[0]}" = "wlan0" ]
 }
 # ── CLI flags: --yes / --allow-destructive ──────────────
 # debianito.sh (the parser) is never sourced in tests:
 # mock_reset seeds the flag globals and the readers under
 # test (_confirm, _branch_migration) are exercised directly.
@test "_confirm auto-accepts when AUTO_YES=1 (no whiptail call)" {
    export AUTO_YES=1
    # Shadow the PATH mock to count invocations: the gate
    # must return before whiptail is ever executed.
    WHIPTAIL_CALLS=0
    whiptail() { WHIPTAIL_CALLS=$((WHIPTAIL_CALLS + 1)); return 1; }
    _confirm "Title" "text"
    [ "$WHIPTAIL_CALLS" -eq 0 ]
 }
@test "_confirm still prompts when AUTO_YES=0" {
    export AUTO_YES=0
    export MOCK_WHIPTAIL_RC=1 # user answers "No"
    run _confirm "Title" "text"
    [ "$status" -eq 1 ]
 }
@test "_branch_migration refuses unattended mode without --allow-destructive" {
    source "${TEST_PROJECT_ROOT}/modules/repos/migrate.sh"
    export AUTO_YES=1
    export ALLOW_DESTRUCTIVE=0
    run _branch_migration
    [ "$status" -eq 1 ]
    [[ "$output" == *"destructive"* ]]
 }