The practical 2026 guide to email deliverability, inboxing, sender reputation, Gmail, Spamhaus, domains, IPs, links, data, and everything else that can send you to spam.

For years, one of the first places email operators went when Gmail delivery started looking strange was Google Postmaster Tools.

You checked Domain Reputation.

You checked IP Reputation.

If Google said "High," you felt pretty good.

If it said "Medium," you started watching things.

If it said "Low" or "Bad," you knew you had work to do.

That era is ending.

As of August 2026, Google has postponed the complete retirement of the legacy Postmaster Tools interface, but the direction is clear. Google's Postmaster Tools v2 does not carry forward the traditional Domain Reputation and IP Reputation dashboards. Google says those dashboards will be retired and replaced by more actionable information. Google also openly acknowledges something experienced email operators have known for years. A reputation label can be misleading because reputation is only one component of deliverability.

That does not mean domain reputation is disappearing.

It does not mean IP reputation is disappearing.

It means Google is becoming less interested in giving you a convenient label describing what it thinks your reputation is.

The underlying reputation systems are still very much alive.

In fact, Google still documents delivery errors specifically related to low IP reputation, low domain reputation, public blocklists, spam-like content, rate limits, and other reputation-related factors.

So now you need to know how to diagnose those things yourself.

That is what this guide is about.

This is not intended to be the final word on every topic below. I could write an entire article about IP warming, another about Spamhaus, another about domains, another about segmentation, another about DKIM, and another about tracking domains.

I probably will.

Consider this the master guide.

If your email is going to spam and you want to understand why, this is where I would start.

Deliverability and Inboxing Are Not the Same Thing

This distinction is incredibly important.

People constantly say things like this.

"My deliverability is 98%."

That usually means 98% of the messages were accepted by the receiving mail servers.

It does not mean 98% reached the inbox.

An email can be successfully accepted by Gmail with a 250 response and immediately placed in spam.

That email was delivered.

It did not inbox.

For the purposes of this article, I use the terms this way.

Deliverability means whether the receiving mail system accepted the message.

Inboxing means whether the message actually reached the primary inbox or another legitimate inbox category rather than spam.

You can therefore have fantastic technical deliverability and horrible inboxing.

That distinction matters because troubleshooting a bounce problem is completely different from troubleshooting spam placement.

If Gmail is rejecting you, look at SMTP responses, authentication, blocklists, rate limits, DNS, infrastructure, and reputation.

If Gmail is accepting everything but placing it in spam, you have a classification problem.

Those are two different problems.

Sender Reputation Is No Longer One Number

There is no single thing called "your reputation."

Modern email filtering evaluates a collection of interconnected reputations and signals.

At minimum, you should assume receivers are evaluating some combination of the following.

• Your sending IP
• Your IP range or surrounding network
• Your domain
• Your organizational or root domain
• Your DKIM signing domain
• Your envelope sender domain
• Your Return-Path domain
• Your From domain
• Your tracking domain
• Domains appearing inside your content
• Redirect domains
• Your final landing page
• Your sending platform
• Your traffic patterns
• Your sending history
• Your message construction
• Your list quality
• Recipient engagement
• Recipient complaints
• Bounce behavior
• Unsubscribe behavior
• Message content
• Message headers
• Authentication
• Your relationship with individual recipients

This is why changing an IP does not necessarily fix a problem.

It is also why changing the From domain does not necessarily fix a problem.

Filters are evaluating an ecosystem.

Think of sender reputation less like a credit score and more like a constantly changing profile.

The receiver is effectively trying to answer four questions.

Who are you?

What are you sending?

Who are you sending it to?

Do those people appear to want it?

Everything else feeds into those questions.

Authentication Is the Starting Line, Not the Finish Line

One of the biggest misconceptions in deliverability is that SPF, DKIM, and DMARC somehow make your email trustworthy.

They don't.

They make your email identifiable.

That distinction is huge.

A perfectly authenticated spammer is still a spammer.

Spamhaus makes essentially the same point. SPF, DKIM, and DMARC are important, but malicious and abusive senders can configure them too. Authentication alone does not create a good reputation.

What authentication does is allow Gmail and other receivers to confidently associate your behavior with an identity.

That identity then earns a reputation.

SPF

SPF tells a receiving system which servers are authorized to send mail for a domain.

Your SPF record needs to include every legitimate system sending mail for that domain.

A common problem occurs when someone changes ESPs, adds a CRM, adds a support platform, adds transactional infrastructure, or creates some other sending source without updating SPF.

Now part of the organization's mail passes SPF and part does not.

That is unnecessary reputation damage.

Google currently requires SPF or DKIM for all senders to personal Gmail accounts. Senders reaching bulk-sender thresholds need both SPF and DKIM.

DKIM

DKIM digitally signs the message.

It allows receivers to verify that the message was authorized by the signing domain and was not improperly modified after signing.

For Gmail, DKIM is particularly important because it provides a persistent domain identity that can follow your traffic across IP addresses.

Google requires at least a 1024-bit DKIM key for Gmail delivery and recommends 2048-bit keys when supported.

Make sure DKIM is actually passing.

Do not stop at "we published the DNS record."

Send a message.

Open the original headers.

Verify it.

DMARC

DMARC adds alignment.

Your visible From domain needs to align with the domain authenticated through SPF or DKIM for DMARC to pass.

For bulk senders to personal Gmail accounts, DMARC is required, although Google currently allows a policy as permissive as p=none.

DMARC reporting is also extremely useful because it tells you who is actually sending on behalf of your domain.

That occasionally reveals systems you forgot existed.

PTR and Reverse DNS

Your sending IP should have proper reverse DNS.

If your IP is 192.0.2.10, its PTR should resolve to a legitimate hostname associated with your mail infrastructure.

That hostname should then resolve forward to the same IP.

Google explicitly requires valid forward and reverse DNS for senders.

Do not treat PTR records as cosmetic.

HELO and EHLO

Your SMTP server introduces itself.

That identity should make sense.

It should not be some generic localhost-style hostname, mismatched server name, obviously temporary VPS hostname, or something unrelated to your mail infrastructure.

Professional infrastructure should look professional from the first SMTP command forward.

TLS

Use TLS.

This is not optional for serious bulk email operations anymore.

Gmail requires TLS for bulk senders and can temporarily or permanently reject non-compliant traffic.

Message Formatting

Make sure messages comply with RFC 5322.

That includes valid headers, a valid Message-ID, sane MIME construction, proper Date headers, proper From headers, and avoiding duplicate headers that should only exist once.

Google specifically calls out malformed messages as a potential cause of delivery problems.

One-Click Unsubscribe

If you are sending marketing or promotional email at Gmail bulk-sender volumes, implement RFC-compliant one-click unsubscribe.

That does not simply mean putting the word "unsubscribe" at the bottom of your message.

The appropriate List-Unsubscribe infrastructure and headers need to exist.

Google requires one-click unsubscribe for marketing and subscription messages sent by bulk senders.

Authentication Does Not Guarantee Inboxing

You can have all of this.

• SPF passes
• DKIM passes
• DMARC passes
• PTR is correct
• TLS works
• One-click unsubscribe works
• The message is RFC compliant

And Gmail can still put everything in spam.

Why?

Because authentication answers this question.

"Who sent this?"

It does not answer this question.

"Do Gmail users want this?"

That second question is where reputation begins.

Data Quality Is Probably More Important Than You Think

If I had to pick the variable that destroys more sending programs than almost anything else, it would be bad data.

People obsess over IPs.

They obsess over domains.

They obsess over subject lines.

Then they send the same garbage list through the new IP and new domain.

Three days later they wonder why the new setup is ruined.

Your recipients are part of your reputation.

Bad data can produce some combination of the following.

• Hard bounces
• Unknown users
• Spam traps
• Long-inactive mailboxes
• Low engagement
• Low clicks
• Low replies
• High complaint rates
• Unsubscribes
• Deletions without engagement
• Messages ignored repeatedly

A perfectly warmed IP cannot indefinitely overcome recipients telling Gmail that they do not care about your mail.

You cannot infrastructure your way out of a fundamentally bad audience.

Complaints Matter Enormously

Google currently recommends keeping the user-reported spam rate in Postmaster Tools below 0.10% and avoiding 0.30% or higher. Gmail's bulk sender enforcement uses 0.30% as an important threshold, but Google explicitly says even rates above 0.10% can negatively impact inboxing.

That means one complaint per thousand inboxed messages is already something you should watch.

Three per thousand is not something I would casually ignore.

There is another catch.

Postmaster Tools spam rate can look artificially wonderful when Gmail is already putting most of your mail in spam.

Why?

Because Gmail calculates that metric from messages delivered to inboxes and subsequently marked as spam.

If Gmail automatically sends most of your traffic to spam, fewer recipients have an opportunity to hit the spam button on inboxed mail.

Google explicitly warns about this. A suspiciously low spam rate can sometimes mean Gmail is already filtering a large percentage of your traffic before users ever see it.

A 0.00% complaint rate does not automatically mean you are healthy.

Context matters.

Open Rates Still Matter, but Not the Way They Used To

Google states that it does not track open rates and cannot verify open-rate data reported by third parties.

That does not mean opens are useless.

It means you should stop treating an open rate as a perfectly accurate measurement of human engagement.

Privacy systems, proxy image loading, bot activity, image caching, and tracking protection have made opens increasingly noisy.

I still watch them.

I just watch the trend more than the exact number.

For a mailing list that I believe is healthy, I would much rather see a measured open rate consistently above 30% than one sitting around 10% to 15%.

That does not mean 30% is a Gmail requirement.

It is not.

Different industries, message types, audiences, and tracking systems can produce wildly different numbers.

The useful question is this.

"What is normal for this particular stream, and is that number getting better or worse?"

If your normal tracked open rate is 38% and it suddenly becomes 19%, something changed.

Investigate.

Clicks Are a Better Signal When the Email Contains a Link

If the purpose of the message is to get someone to click, watch clicks.

Clicks generally represent stronger intent than an open.

A recipient may open by accident.

A privacy system may generate an open.

A click usually requires something more.

That said, security scanners and automated systems can also visit links, so click data is not perfectly clean either.

Again, watch your baseline.

If a campaign usually generates healthy clicks and suddenly generates almost none, I care.

If you are sending link-heavy promotional mail and supposedly getting massive opens with almost no clicks, I would question how meaningful those opens actually are.

If There Are No Links and No Open Tracking, Watch Replies

Sometimes I intentionally want a message with almost nothing measurable inside it.

No tracking link.

No open pixel.

Maybe no link at all.

In that case, replies become extremely useful.

A reply is an unmistakably strong form of engagement.

If people are replying to you, they are interacting with the sender.

For conversational mail, sales outreach, relationship-based newsletters, or mail designed specifically to create dialogue, I care far more about replies than pixel-based opens.

There is no universal "good reply rate" because a newsletter, political appeal, ecommerce promotion, and one-to-one sales message are completely different products.

What matters is establishing your normal reply rate and protecting it.

Plain Text Is One of My Favorite Deliverability Tests

When I want to know whether a domain and IP can inbox, I like stripping the message down.

Start with plain text.

No images.

No HTML template.

No buttons.

No tracking pixel.

No click-tracking redirect.

No affiliate link.

No complicated footer.

No remote assets.

No marketing template.

Just legitimate, human-readable text.

Why?

Because you have removed an enormous number of variables.

A plain-text diagnostic email does not magically receive a Gmail "plain text bonus."

Google does not publish such a rule.

But plain text frequently performs better during diagnosis because there is simply less that can be wrong.

You have removed links.

You have removed redirect chains.

You have removed tracking domains.

You have removed image hosts.

You have removed questionable HTML.

You have removed template fingerprints.

You have removed hidden CSS problems.

You may have removed platform tracking.

That makes plain text an incredibly useful control.

Google itself notes that internet links can increase the possibility of a message being treated as spam.

HTML Introduces More Things That Can Go Wrong

HTML email can inbox beautifully.

Billions of HTML emails reach inboxes every day.

The problem is not "HTML equals spam."

The problem is that HTML introduces additional signals.

A typical commercial HTML email may contain all of this.

• Open-tracking pixel
• Click-tracking domain
• Image CDN
• Multiple destination domains
• Redirect parameters
• List-Unsubscribe links
• View-in-browser links
• Social links
• Tracking parameters
• Template-specific HTML
• Platform-specific headers
• Hosted images
• CSS
• Tracking identifiers

Every one of those is another variable.

That is why my diagnostic sequence is usually additive.

How I Test Whether a Setup Can Inbox

Do not change eight things at once.

Change one category at a time.

Test 1

Send plain text with no links and no tracking.

If that spams, I immediately become more suspicious of the IP, domain, data, authentication, sending pattern, or broader infrastructure.

Test 2

Send simple HTML with tracking disabled.

No links yet.

If plain text inboxes but simple HTML spams, investigate the message construction and platform.

Test 3

Add one clean first-party link.

Use a domain you trust.

If inboxing deteriorates, investigate the linked domain.

Test 4

Add the final landing page you actually intend to use.

Test 5

Enable click tracking.

Test 6

Enable open tracking.

Test 7

Introduce the full production creative.

At each stage you are asking one question.

"What changed when placement changed?"

That is far more useful than sending ten completely different creatives through three domains and four IPs and trying to infer something from the chaos.

Tracking Links Can Hurt You

Most ESPs rewrite links.

You think the email contains this.

https://example.com/article

The recipient may actually receive something functionally closer to this.

https://track.example-mail.net/c/abc123...

That URL redirects to the final page.

The tracking domain is now part of your message.

Its reputation matters.

If it is shared with other senders, their behavior may matter.

If it has been heavily abused, that matters.

If the domain was recently registered and suddenly appears in huge volumes of commercial mail, that can matter.

If the redirect ultimately lands on something questionable, that can matter too.

Turning off click tracking is therefore one of the first things I test when placement suddenly collapses.

The Final Landing Page Matters Too

Do not assume the only URL that matters is the one visible in the email.

Email security systems analyze links.

Google operates link-protection systems specifically because URLs inside messages can lead users to malicious or unwanted destinations.

Spamhaus' DBL is also specifically designed to evaluate domains appearing in email content and headers, including domains used in URLs.

Assume filters can care about the entire path.

That may include the following.

1. The visible URL
2. Your tracking domain
3. Intermediate redirects
4. Affiliate redirects
5. The final landing page
6. Domains loaded by that landing page
7. Infrastructure historically associated with those domains

This creates a problem I see surprisingly often.

The sending domain is clean.

The IP is clean.

SPF passes.

DKIM passes.

The email itself looks fine.

But every message contains a link to a domain with a terrible history.

Changing the sending IP will not fix that.

Content Still Matters

There was a time when people talked about "spam words" like the filter was simply counting how many times you used "FREE" or how many exclamation points appeared in the subject line.

Modern filtering is far more sophisticated.

There is no magical list of words that automatically sends a message to spam.

Context matters.

That does not mean content is irrelevant.

Gmail explicitly documents "email content is possibly spammy" as a delivery problem and notes that links can contribute to classification.

Things I would watch include the following.

• Misleading subject lines
• Fake Re: or Fwd: subjects
• Deceptive display names
• Hidden HTML
• Hidden text
• Obfuscated content
• Link destinations that do not match expectations
• Suspicious attachments
• Image-only messages
• Extremely malformed HTML
• URL shorteners
• Excessive redirects
• Misleading buttons
• Phishing-like language
• Impersonation
• Strange character substitutions
• Brand mismatches
• Content radically different from your normal traffic

Google specifically warns against deceptive headers, misleading display names, fake reply-style subjects, hidden HTML and CSS, and links where users cannot understand what they are clicking.

The important point is that content reputation and sender reputation interact.

A strong sender can sometimes survive mediocre content.

A weak sender may not.

What Is an Email Footprint?

This is one of the most important concepts in modern deliverability.

A footprint is the collection of technical and behavioral signals that allows receiving systems, reputation companies, blocklists, and security systems to associate one stream of email with another.

A footprint is not automatically bad.

In fact, legitimate senders should have consistent footprints.

Your DKIM identity is a footprint.

Your From domain is a footprint.

Your IP is a footprint.

Consistency helps receivers understand who you are.

The problem is a bad footprint.

A bad footprint associates your mail with infrastructure, domains, URLs, platforms, or behavior that already has a poor reputation.

Examples of Sending Footprints

A receiving system may be able to correlate traffic through things such as these.

• Sending IP
• IP range
• ASN
• Reverse DNS
• HELO hostname
• DKIM domain
• DKIM selector patterns
• Envelope sender
• Return-Path
• Bounce domain
• From domain
• Reply-To domain
• Message-ID hostname
• Message-ID format
• Tracking domain
• Tracking URL structure
• Image-hosting domain
• List-Unsubscribe domain
• List-ID
• X-Mailer
• ESP-specific X headers
• MIME construction
• Header ordering
• Template HTML
• Redirect patterns
• URL parameters
• Source IPs exposed inside Received headers
• Platform relay hostnames
• Landing pages
• Sending cadence
• Similar creatives
• Similar recipient populations

You do not need to assume every provider uses every signal.

The point is that changing the visible From domain does not necessarily make you a completely different sender.

Sending Platform Footprints Matter

This deserves special attention.

Suppose an ESP has thousands of customers.

Messages from those customers might share certain technical characteristics.

Perhaps they use similar bounce domains.

Perhaps Message-ID construction is similar.

Perhaps the same tracking infrastructure appears repeatedly.

Perhaps mail travels through recognizable relay hosts.

Perhaps custom headers identify the platform.

None of that is necessarily bad.

Large legitimate platforms have obvious footprints too.

The problem is what happens when a platform becomes heavily associated with low-quality traffic.

If a provider repeatedly attracts bad senders, receivers can become cautious about traffic associated with that infrastructure.

This is one reason changing from one sending platform to another can occasionally change placement even when your own domain remains unchanged.

Source IPs Inside the Message Can Matter

Do not look only at the IP making the final SMTP connection.

Open the raw source.

Look at the complete Received: chain.

Some sending systems expose upstream injection servers.

Some expose internal hostnames.

Some expose originating IP addresses.

Some reveal relay infrastructure belonging to another provider.

Those signals may give receiving systems additional context.

If an upstream platform has a terrible history, hiding behind a new outbound IP does not necessarily erase every relationship with that infrastructure.

Again, the answer is not to start manipulating headers to conceal who you are.

That creates a completely different problem.

The answer is to use clean infrastructure.

Do Not Try to Hide Your Footprint

This is where some operators make a huge mistake.

They learn about footprints and conclude that the solution is randomization.

Random Message-IDs.

Constantly changing domains.

New tracking hosts.

Rotating IPs.

Changing DKIM selectors constantly.

Different hostnames every few days.

Random From addresses.

That does not necessarily make you invisible.

It can make you look like a snowshoe spammer.

Legitimate mailers generally benefit from durable, understandable identities.

Reputation is an asset.

You want to build it.

Not continuously throw it away.

What Is Snowshoe Spamming?

The term comes from an actual snowshoe.

A snowshoe spreads a person's weight across a large surface area so they do not sink deeply into snow.

Snowshoe spamming applies the same idea to email.

Instead of sending a large volume from a small number of recognizable IPs and domains, the sender spreads that traffic across large numbers of IPs and domains.

The idea was to dilute reputation.

Rather than send 1,000,000 messages from one identity, a sender might historically try spreading traffic across dozens or hundreds of IPs and domains so each one appeared to have lower volume.

Spamhaus defines snowshoe spam in essentially these terms. The technique spreads spam across many IPs and domains to dilute reputation metrics and evade filtering. Spamhaus also specifically warns that domains behaving like snowshoers can be treated like snowshoers.

This used to work much better than it does today.

Modern filtering systems correlate infrastructure.

Creating 100 mediocre domains does not give you 100 trustworthy identities.

It may simply give the receiving system 100 reasons to believe you are trying to avoid reputation.

Too Many Domains Can Be Worse Than One Good Domain

I regularly see senders terrified of putting volume through one domain.

So they build enormous domain farms.

That can be exactly backwards.

Reputation requires history.

A domain that sends legitimate, wanted email consistently for years can become extremely valuable.

A collection of constantly rotating domains has very little opportunity to build durable trust.

Spamhaus specifically notes that reputable bulk senders invest time into persistent domains and IPs and therefore tend to use fewer of them than snowshoe operations.

Google's own sender guidance also says that, ideally, senders should send messages from the same IP address and maintain consistent traffic patterns.

The old strategy was often this.

"The domain went bad. Throw it away."

Then another.

Then another.

Then another.

Eventually the rotation itself becomes part of the reputation problem.

Yes, You Can Send More Than One Million Emails From One IP

There is no rule saying a high-volume sender needs dozens of IP addresses.

A properly warmed dedicated IP with good recipient engagement, stable traffic, strong authentication, clean infrastructure, and established history can handle enormous volume.

That can include more than one million messages per day.

That can even mean very large volumes primarily or entirely destined for Gmail.

The SMTP capacity of a modern mail server is usually not the interesting part.

Receiver trust is.

Gmail can throttle traffic.

It can defer mail.

It can adjust limits based on IP and domain behavior.

Google explicitly says it tracks volume and limits at both domain and IP levels and recommends gradual increases and consistent sending rates.

There is therefore no magical statement like this.

"One IP can send exactly 500,000 Gmail messages."

It does not work that way.

A sender with excellent history may be able to push volumes that would destroy a brand-new IP.

Gmail Does Not Have a Published "Test 10,000 Then Release the Rest" Rule

People often notice something interesting during large campaigns.

The first portion inboxes.

Then placement changes.

Or the first portion spams and later traffic improves.

Or Gmail begins deferring traffic partway through a campaign.

This leads to theories like this.

"Gmail tests the first 10,000 messages."

Or 5,000.

Or 20,000.

Or 50,000.

I would not build an operating strategy around any fixed number.

Google does not publish a universal test batch.

What Gmail clearly does is continuously evaluate traffic.

Volume matters.

Recipient feedback matters.

Sending speed matters.

Authentication matters.

Reputation matters.

Gmail also applies rate limits and temporary failures when traffic appears suspicious. Google recommends consistent sending instead of bursts and explicitly tells senders to gradually increase volume.

Think of Gmail as continuously reevaluating the stream rather than conducting one single test.

This explains why a campaign can start well and deteriorate.

Your reputation is not frozen when the first message leaves the server.

Seed Testing Is Useful, but Seeds Are Not the Truth

I use seed accounts.

I like seed testing.

I would never use seed placement as the sole definition of my reputation.

Seeds have limitations.

A seed Gmail account does not necessarily behave like a normal recipient.

It may have little historical interaction with you.

It may receive unusual amounts of test email.

Its mailbox behavior may be artificial.

The relationship between that account and your sender can differ dramatically from the relationship between your sender and a real subscriber.

Gmail also personalizes filtering.

A recipient who regularly opens your mail may see inbox placement while someone who has ignored you for six months sees spam.

This means you can send the exact same message through the exact same infrastructure and receive different placement for different recipients.

Seeds give you evidence.

They do not give you absolute truth.

How I Use Seeds

I am looking for patterns.

If ten Gmail seeds spam simultaneously after a domain change, I care.

If one of ten spams, I care less.

If plain text inboxes everywhere but the production creative spams everywhere, that is valuable information.

If Domain A spams across multiple known-good IPs while Domain B inboxes through those same IPs, that is valuable information.

Seeds become powerful when you use them as part of controlled testing.

They become dangerous when you treat one mailbox as an oracle.

Blacklists and Blocklists

The terms "blacklist," "blocklist," DNSBL, and RBL are frequently used interchangeably.

The industry increasingly prefers "blocklist."

A blocklist is essentially a reputation dataset containing IP addresses, domains, or other identifiers associated with unwanted or risky behavior.

Receiving systems can query those datasets and decide what to do.

They may reject the mail.

They may place it in spam.

They may increase its spam score.

They may simply use the listing as one signal among many.

Spamhaus explains that its blocklists can be used either to reject mail in real time or to tag mail for additional filtering.

Not every blacklist matters equally.

Being listed on some obscure DNSBL that virtually nobody uses may have no meaningful impact.

Being listed by Spamhaus is a very different situation.

The Spamhaus Lists You Should Understand

Spamhaus maintains several different datasets.

SBL

The Spamhaus Blocklist focuses on IP addresses associated with spam sources and related abuse.

CSS

Combined Spam Sources focuses heavily on IPs associated with low-reputation SMTP traffic.

Spamhaus specifically says potential CSS triggers include unsolicited email, poor marketing list hygiene, compromised systems, and snowshoe behavior.

XBL

The Exploits Blocklist focuses on compromised systems and malware-related activity.

PBL

The Policy Blocklist includes IP space that generally should not be sending mail directly to recipient MX servers, such as many residential broadband ranges.

ZEN

ZEN combines several Spamhaus IP-oriented datasets into one query system.

DBL

The Domain Blocklist is different.

DBL is for domains.

Spamhaus describes DBL as a list of domain names with poor reputation. Those domains may appear in email headers, URLs, or other message components.

That distinction matters.

Checking your IP and seeing "clean" does not mean the domains inside your message are clean.

How to Check Your IP and Domain Against Blocklists

I usually start with three things.

Spamhaus Reputation Checker

Check the sending IP.

Check the sending domain.

Check important tracking and landing domains where appropriate.

Spamhaus provides its own IP and Domain Reputation Checker specifically for this purpose.

MXToolbox

MXToolbox can check an IP against a large number of DNS-based blocklists and is useful as a broad first pass.

MultiRBL

MultiRBL is another useful way to see listings across many DNSBLs and can also help identify reverse DNS issues.

Do not just count listings.

Ask which list you are on.

Ask why.

Ask how widely that list is used.

Ask whether your SMTP rejection messages reference it.

One serious listing is more important than twenty irrelevant ones.

Spamhaus Probably Knows More About You Than You Think

There is a common assumption among senders that if they avoid obvious spam traps, Spamhaus cannot see them.

I would not make that assumption.

Spamhaus says its reputation systems use many sources, automated systems, heuristics, intelligence partnerships, machine learning, manual investigations, and large-scale visibility into email activity. It intentionally does not reveal all listing criteria or data sources.

There is also a common operator theory that moving traffic exclusively to Gmail can reduce exposure to external trap networks.

There may be situations where a sender observes exactly that.

But I would not turn the observation into the statement that Spamhaus has "no Gmail seeds."

Spamhaus does not publish enough information about its data collection for anyone outside Spamhaus to responsibly guarantee that.

What I am comfortable saying is this.

A Spamhaus listing and Gmail's internal reputation are two different things.

You can have a Spamhaus problem and still inbox Gmail.

You can be completely clean on Spamhaus and spam at Gmail.

A public blocklist is not Gmail's internal reputation database.

Should You "Just Mail Gmail" to Get Off Spamhaus?

I have seen cases where a sender stops the traffic that appears to be triggering an external reputation system, continues sending a cleaner subset elsewhere, and eventually sees a listing disappear.

Some operators interpret this as "mail Gmail until Spamhaus forgets about you."

I would treat that as an observation, not a guaranteed delisting procedure.

Spamhaus' official guidance is to stop the behavior causing the listing, correct the problem, use its Reputation Checker, and follow the removal instructions associated with the listing. Many DBL listings also expire automatically after the activity that triggered them stops.

If sending only clean, wanted Gmail traffic happens to be part of your recovery process, fine.

But do not assume you have discovered an invisible lane where Spamhaus cannot observe anything you do.

That is too strong a claim.

Domain Reputation and IP Reputation Affect Each Other

Another mistake is treating domain and IP reputation like completely independent universes.

They are not.

Spamhaus explicitly notes that domain and IP reputations affect each other.

Email receivers can also correlate them.

If ten terrible domains repeatedly appear on the same IP, what does that say about the IP?

If one supposedly "clean" domain repeatedly moves from one terrible IP to another, what does that say about the domain?

Reputation is relational.

That is another reason indiscriminate rotation is dangerous.

How Subdomain Reputation Actually Works

People often ask this.

"If example.com is bad, can I just send from mail.example.com?"

Maybe.

But do not think of a subdomain as a completely unrelated identity.

A subdomain can build its own sending history.

news.example.com can develop signals that differ from transactional.example.com.

That functional separation can be useful.

But receivers can still understand that both belong to example.com.

Google explicitly aggregates the bulk sender threshold across the same primary domain. If example.com and promotions.example.com together cross Gmail's bulk-sender threshold, Google treats the primary domain as the common identity for that calculation.

Spamhaus DBL also has root-domain implications. If a domain is listed at the registrable level, subdomains of that domain can return the same DBL result.

So no, a subdomain should not be viewed as a magic reputation reset.

When a Subdomain Makes Sense

Use subdomains when you want logical separation while maintaining the same organizational identity.

For example.

• news.example.com
• offers.example.com
• receipts.example.com
• alerts.example.com

This can help separate traffic streams.

Promotional mail behaves differently from password resets.

Password resets should not suffer because a marketer accidentally sent an aggressive promotion to an old segment.

Google and Yahoo both recommend separating different mail types in various ways, including IP or sending identity separation.

That is legitimate reputation management.

When a Completely New Domain Makes Sense

A separate domain can make sense when you genuinely want an independently managed identity.

Maybe it is a different brand.

Maybe it is a separate business unit.

Maybe you need strong risk separation.

Maybe the original domain has sustained serious reputation damage.

Maybe the root domain itself is on a domain blocklist.

What I would not do is create new domains every week because yesterday's domain stopped inboxing.

That is exactly the operational pattern you do not want.

When to Swap an IP

Do not replace an IP because one Gmail seed went to spam.

Diagnose first.

A strong indication of an IP problem looks like this.

Domain A + IP 1 spams

Domain A + IP 2 inboxes

Keep the following as controlled as possible.

• Same domain
• Same creative
• Same links
• Same recipient quality
• Same sending rate
• Same authentication

If changing only the IP consistently changes placement, the IP becomes the obvious suspect.

Additional evidence includes the following.

• IP-specific SMTP deferrals
• IP blocklist listings
• Low-IP-reputation errors
• Other domains failing on the same IP
• The same domain performing normally through a proven clean IP

At that point, moving traffic may make sense.

When to Swap a Domain

Now reverse the test.

Domain A + IP 1 spams

Domain A + IP 2 spams

But this happens.

Domain B + IP 1 inboxes

Domain B + IP 2 inboxes

Now the domain becomes much more suspicious.

Before throwing it away, test plain text.

Remove links.

Remove tracking.

Check DKIM.

Check SPF.

Check DMARC.

Check the domain against Spamhaus DBL.

Check the root domain.

Check landing pages.

Check sending history.

Check whether the domain was previously used.

If the domain continues failing across multiple known-good IPs with simple, clean messages while another domain works through those same IPs, replacing the domain may be justified.

The Simple Domain and IP Diagnostic Matrix

This is far more useful than guessing.

If the Same Domain Fails Across Multiple IPs

Assuming your testing is controlled, I become increasingly suspicious of the domain.

That includes domains related to the message, not merely the visible From address.

Maybe the problem is the From domain.

Maybe it is the DKIM domain.

Maybe it is the tracking domain.

Maybe it is the landing domain.

Maybe the entire root domain has developed a bad reputation.

You need to isolate them.

If the Domain Works Through Another IP

Then the original IP deserves serious scrutiny.

That does not automatically mean it is permanently dead.

Maybe you pushed volume too fast.

Maybe it needs recovery.

Maybe it inherited history from a previous tenant.

Maybe another customer used the IP before you.

Maybe it sits inside a problematic network.

Maybe the reputation is temporarily low.

But at least you now know the domain is capable of inboxing through other infrastructure.

That is valuable.

The Data Test Nobody Wants to Perform

Sometimes everything is clean.

Then you change the recipients.

Suddenly you inbox.

That tells you something nobody wants to hear.

Your infrastructure was not the problem.

Your list was.

This is why I always want a known-good engaged segment available for testing.

Without that control, you can waste days moving infrastructure around when the recipients are actually destroying the campaign.

My 10% Rule for Questionable Data

Let me define "questionable" first.

I mean data where I have less confidence than I do in my established engaged audience.

Maybe it is older.

Maybe the source is less proven.

Maybe it has lower historical engagement.

Maybe I am testing a new acquisition source.

I generally do not want that data suddenly becoming half of my traffic.

My operating rule is roughly 10%.

If I have a healthy established stream and I am going to test lower-confidence data, I do not want it representing more than roughly 10% of the day's volume.

And 10% is a ceiling.

It is not a promise that you can add 10% garbage every day forever.

If engagement takes a beating, stop.

If clicks collapse, stop.

If replies collapse, stop.

If complaints rise, stop.

If bounces rise, stop.

If Gmail placement deteriorates, stop.

Your reputation tells you how much experimentation it can tolerate.

Also remember that provider policies and applicable laws still matter. Google explicitly advises senders not to purchase email addresses and not to send messages to people who did not sign up to receive them.

So do not interpret my 10% rule as permission to ignore consent or provider policies.

It is a reputation-risk rule for testing lower-confidence segments within an otherwise healthy operation.

How to Maintain Good Engagement

Do not wait for a deliverability emergency before segmenting.

Build engagement segmentation from the beginning.

Useful populations can include the following.

• Clicked within 7 days
• Clicked within 14 days
• Clicked within 30 days
• Clicked within 60 days
• Opened within 7 days
• Opened within 14 days
• Opened within 30 days
• Replied recently
• Purchased recently
• Converted recently
• Signed up recently
• Active subscribers
• Long-term inactive recipients

Clicks, replies, purchases, and conversions are generally more meaningful to me than opens alone.

Open data is still useful.

It just needs context.

What to Do When Emails Start Going to Spam

Do not panic and immediately change everything.

That destroys your ability to identify the problem.

Start reducing risk.

Mild Deterioration

Maybe some seeds are shifting.

Maybe open rates softened.

Maybe clicks declined.

Maybe Gmail placement is less consistent.

Tighten your segment.

Move toward people who engaged within the last 30 days.

Reduce questionable data.

Watch complaints.

Watch temporary failures.

Keep volume steady rather than violently turning traffic on and off.

Clear Spam Placement

If Gmail is clearly pushing a meaningful percentage of traffic into spam, tighten harder.

Start with recent clickers, repliers, buyers, converters, and highly engaged recipients.

A 14-day engagement window may make sense.

If the situation is serious, go tighter.

Severe Reputation Damage

When placement has collapsed, I want the strongest possible audience.

That might mean 7-day clickers and repliers.

It might mean very recent purchasers.

It might mean active subscribers with repeated engagement.

The exact number of days is not sacred.

The principle is.

As reputation gets worse, recipient quality needs to get better.

Do Not "Warm" a Broken Reputation With Bad Data

This sounds obvious, yet people do it constantly.

They discover an IP is struggling.

Then they continue pushing the full database through it because "we need volume to warm it."

That is not warming.

That is reinforcement.

The receiver sees more unwanted behavior and becomes increasingly confident that its original classification was correct.

Warm with your best recipients.

Recover with your best recipients.

Expand only after the strongest traffic performs correctly.

Reputation Recovery Should Be Earned

I generally think of recovery as a ladder.

1. Start with the strongest engagement cohort.
2. Send consistently.
3. Verify inbox placement.
4. Watch complaints.
5. Watch clicks or replies.
6. Watch SMTP responses.
7. Expand the audience slightly.
8. Repeat.
9. Stop expanding when metrics deteriorate.

Do not decide in advance that you are increasing volume 100% every day no matter what happens.

The audience decides whether you deserve the next step.

Building Reputation on a New Domain and IP

A completely new domain on a completely new dedicated IP is the most difficult starting point because almost everything is unknown.

Before sending production traffic, make sure the technical foundation is complete.

Preflight Checklist

• SPF passes
• DKIM passes
• DMARC exists
• PTR is correct
• Forward DNS matches
• HELO is sensible
• TLS works
• Message-ID is valid
• From alignment is correct
• Bounce handling works
• Complaints can be processed
• One-click unsubscribe works when required
• Tracking domain is clean
• Landing domain is clean
• IP is not blocklisted
• Domain is not blocklisted
• Postmaster Tools is configured
• Sending rate is controlled
• Feedback IDs are configured when useful

Then begin with your best recipients.

Not random people.

Not your oldest segment.

Not the file somebody bought three years ago.

Your best recipients.

Do Not Obsess Over an Exact Warming Schedule

I have seen warming guides that say things like this.

Day 1 sends exactly X.

Day 2 sends exactly Y.

Day 3 sends exactly Z.

That creates false confidence.

A mature brand moving an established domain onto a fresh IP is very different from a brand-new domain sending unknown data from a brand-new IP.

Google does not publish a universal warming calendar.

It tells senders to start with low volume, send to engaged users, increase gradually, maintain consistent rates, and monitor the response.

That is how I look at warming.

Your ramp should be conditional.

If everything looks fantastic, expand.

If metrics weaken, hold.

If placement collapses, reduce.

Consistency Is Hugely Important

A common bad sending pattern looks like this.

Monday sends 20,000.

Tuesday sends nothing.

Wednesday sends 700,000.

Thursday sends 10,000.

Friday sends 1,500,000.

Then silence for four days.

That is not a stable identity.

Google specifically recommends consistent sending rates and warns against burst-style sending.

If you expect to become a million-message-per-day sender, behave like a sender gradually becoming a million-message-per-day sender.

Do not behave like someone who discovered SMTP yesterday.

Dedicated IPs vs Shared IPs

Neither option is automatically better.

They solve different problems.

Shared IP Advantages

• Reputation may already exist
• Lower-volume senders do not need to establish an entire IP identity alone
• Provider manages much of the infrastructure
• Easier startup
• Less operational overhead
• Good providers actively police the pool

Shared IP Disadvantages

• Other customers influence the IP
• A bad neighbor can hurt everyone
• You cannot fully control sending patterns
• You cannot control all remediation decisions
• Blocklist issues may originate with someone else
• Troubleshooting becomes more complicated

Google explicitly acknowledges this tradeoff. The activity of senders sharing an IP can affect the reputation and delivery of everyone on that IP.

Dedicated IP Advantages

• Your behavior controls the reputation
• Easier attribution
• Better for consistently high volume
• Greater infrastructure control
• Easier IP-specific testing
• You are not directly sharing reputation with random customers

Dedicated IP Disadvantages

• You must build reputation
• You must maintain reputation
• Low or inconsistent volume can be problematic
• You are responsible when something goes wrong
• A new or recycled IP may have unknown history

If you send enough legitimate volume to maintain your own reputation, I generally prefer the control of dedicated infrastructure.

If you send sporadically or at low volume, a high-quality shared pool can make more sense.

Shared Does Not Automatically Mean Bad

A good shared pool can be fantastic.

The important word is good.

A competent ESP actively removes abusive customers, manages traffic, monitors reputation, handles complaints, and protects the pool.

A terrible shared platform accepts anyone with a credit card and waits until receivers punish the IPs.

Those are completely different products.

Google specifically recommends that providers remove customers who use their infrastructure to send spam.

The quality of the provider matters.

Dedicated Does Not Automatically Mean Good

I can give you a dedicated IP right now.

That tells you nothing about whether Gmail likes it.

Maybe it previously belonged to a terrible sender.

Maybe the range has a bad history.

Maybe the upstream network is questionable.

Maybe reverse DNS is broken.

Maybe your domain is bad.

Maybe your data is terrible.

Ownership is not reputation.

Sometimes a Setup Simply Fails

This is something people rarely admit.

You can configure everything correctly and still have a setup that never performs the way you expected.

Maybe the IP history is worse than you realized.

Maybe the subnet has baggage.

Maybe the hosting network has a poor reputation.

Maybe the domain had prior usage.

Maybe another related domain contaminated the ecosystem.

Maybe your landing page is the problem.

Maybe the reputation system made an association you cannot see.

Maybe your initial traffic was simply too poor.

Email reputation systems are probabilistic.

You are not going to win 100% of the time.

If you build enough infrastructure, some percentage of it will underperform.

Your job is to diagnose rather than become emotionally attached to the setup.

Domain Age Is Not Magic

An old domain can have a terrible reputation.

A new domain can eventually build a fantastic reputation.

Age is context.

History matters more.

Spamhaus notes that unknown domains begin with greater risk because they lack established history, while legitimate use over time can build positive reputation.

Buying an old domain does not automatically buy good email reputation.

Sometimes you buy the opposite.

Website and Hosting Reputation Can Matter

Your email domain does not live in isolation.

Spamhaus specifically mentions hosting, DNS, infrastructure, ownership, registration, usage patterns, and associations when discussing domain reputation.

That means I care about where the domain points.

I care about where the website lives.

I care about nameservers.

I care about historical associations.

I care about the landing domain.

A clean sending IP does not absolve a domain living inside a sketchy infrastructure ecosystem.

Separate Transactional and Marketing Traffic

Please do not send password resets, receipts, account alerts, and aggressive promotional campaigns through one indistinguishable reputation stream if you can reasonably separate them.

Transactional mail has a very different engagement profile.

Recipients expect it.

They often need it immediately.

Promotional mail carries more complaint risk.

Separate them logically.

That might mean different subdomains.

It might mean different DKIM identities.

It might mean different IPs.

It might mean all three.

Google explicitly recommends separating message types when multiple IPs are used, and Yahoo recommends segregating different mail types by IP or DKIM domain.

Protect the important stream.

Your From Address Should Be Boring

That is a compliment.

Receivers like identities they understand.

Recipients like identities they understand.

Do not constantly change this.

newsletter@example.com

deals@example.com

alerts@example.com

Those make sense.

Google specifically recommends using consistent From addresses for consistent categories of mail.

Do not try to trick people into thinking an automated marketing blast is part of an existing conversation.

Fake Re: subjects are not clever.

They are deceptive.

Google explicitly calls them out.

Bounce Handling Matters

Hard bounces should be removed quickly.

Repeatedly mailing nonexistent addresses is a terrible signal.

Temporary failures need different handling.

Do not permanently suppress every temporary error immediately.

Temporary failures can represent rate limiting or temporary receiver problems.

For Gmail-specific temporary failures, Google recommends slowing down and using exponential backoff rather than hammering the receiver harder.

Your MTA needs to understand the difference between these things.

A good email system does not simply say "bounce."

It understands the response.

Rate Limits Are Feedback

If Gmail starts temp-failing traffic because of suspicious volume, do not treat Gmail like an enemy firewall you need to defeat.

It is giving you information.

Slow down.

Google explicitly recommends stopping briefly when appropriate, resuming at a slower rate, and maintaining a constant sending pattern when encountering rate-related issues.

Receivers are telling you what they are willing to accept from your current reputation state.

Listen.

Engagement Is Not Just About Today's Campaign

Reputation is cumulative.

Imagine this.

You spend three months building beautiful engagement.

Then somebody finds an old database and decides to mail all of it Friday afternoon.

The damage from that campaign does not necessarily end Friday afternoon.

Google notes that high spam rates can continue affecting classification and that reputation recovery takes time.

Reputation is an asset that can be spent.

Bad campaigns spend it very quickly.

A Good Segment Protects a Weak Setup

When a domain is recovering, your best users become your reputation repair crew.

Send people who know you.

Send people who recently clicked.

Send people who recently replied.

Send people who purchased.

Send people who requested your content.

Send subscribers who consistently interact.

Those recipients create the behavioral evidence you need.

A Bad Segment Can Destroy a Great Setup

The opposite is also true.

I do not care how beautiful your DNS is.

If Gmail users repeatedly ignore and complain about your mail, Gmail will eventually notice.

Google openly says that frequent spam reports can lower a domain's reputation and make future messages more likely to be classified as spam.

Reputation follows behavior.

Why Removing Links Can Suddenly Fix Placement

This is one of the most useful tests you can perform.

You send your normal HTML creative.

Spam.

You remove every link.

Inbox.

What does that tell you?

It does not automatically identify the exact bad URL.

But it dramatically narrows the investigation.

Now inspect these.

• Tracking domain
• Redirect domain
• Landing page
• Affiliate URL
• Image domains
• Unsubscribe URL
• View-in-browser domain
• Social links
• Link shorteners

Add them back gradually.

Find the trigger.

Why Turning Off Tracking Can Help

Open tracking generally adds an invisible remote image.

Click tracking generally rewrites URLs.

That means enabling tracking changes the email.

It introduces new infrastructure.

If your ESP's tracking environment has reputation problems, your perfectly good domain can suddenly become associated with questionable URLs.

This does not mean tracking is inherently bad.

It means tracking is another reputation dependency.

Know what you are depending on.

What About Link Shorteners?

I generally avoid generic public URL shorteners in bulk email.

They are heavily abused.

They also hide the final destination from recipients.

Google explicitly says links should be clear and recipients should understand what they are clicking.

Use a legitimate branded tracking domain whenever possible.

It is easier to understand.

It is easier to manage.

It gives you greater control over reputation.

Look at the Entire Raw Message

A deliverability person should be comfortable reading email headers.

Do not depend entirely on the ESP dashboard.

Open the message source.

Look at these.

• Authentication-Results
• Received
• DKIM-Signature
• Return-Path
• Message-ID
• List-Unsubscribe
• List-Unsubscribe-Post
• From
• Reply-To
• MIME boundaries
• Content-Type
• Source hostnames
• Relay IPs

This tells you what Gmail actually received.

What your platform claims it sent is less important.

Check the Gmail Authentication Result Yourself

Send a real message to Gmail.

Open it.

Use "Show original."

You want SPF, DKIM, and DMARC doing exactly what you think they are doing.

Gmail also surfaces "mailed by" and "signed by" information to users when authentication is working.

Never assume DNS configuration equals successful authentication.

Verify the actual message.

What to Monitor Now That Reputation Dashboards Are Going Away

This is the real question.

If Google stops showing you a neat little "High / Medium / Low / Bad" chart, what replaces it?

I would watch a basket of signals.

Gmail Postmaster Tools

Watch the following where available.

• Spam rate
• Compliance
• Authentication
• Delivery errors
• Feedback Loop
• Encryption
• SMTP-related problems

The old reputation chart was never the entire answer anyway.

Google's own explanation for replacing it is that reputation changes slowly, can be difficult to act on, and represents only one factor in deliverability.

SMTP Responses

Read them.

Do not simply count bounces.

Seed Placement

Use it directionally.

Engagement

Watch opens, clicks, replies, purchases, conversions, and unsubscribes.

Blocklists

Check important IP and domain lists.

Volume

Know whether your traffic is stable.

Data Mix

Know what percentage is highly engaged versus experimental or lower confidence.

Infrastructure Changes

Document them.

If placement collapses Tuesday and somebody changed your tracking domain Monday night, that matters.

Build a Deliverability Change Log

This is one of the easiest improvements any serious sender can make.

Keep a record of changes.

For example.

When something breaks, you have history.

Without a change log, every deliverability investigation starts with this conversation.

"Did anyone change anything?"

Followed by ten people saying no.

Then three hours later someone remembers they changed the entire sending configuration.

Document everything.

The Biggest Mistake Is Changing Too Many Variables

Suppose email is spamming.

You immediately do all of this.

• New IP
• New domain
• New tracking domain
• New creative
• New ESP
• New segment
• New sending rate

Then it inboxes.

Congratulations.

You learned absolutely nothing.

You have no idea which change fixed the problem.

The next time it happens, you will have to replace everything again.

Controlled testing creates knowledge.

Random rotation creates superstition.

A Practical Spam Diagnosis Workflow

When a campaign starts spamming, this is roughly how I think.

Step 1

Determine whether the messages are being accepted or rejected.

If rejected, read the SMTP response.

Step 2

Verify authentication.

SPF.

DKIM.

DMARC.

PTR.

TLS.

Step 3

Check the sending IP and relevant domains against important blocklists.

Step 4

Send a plain-text message with no links and no tracking to controlled accounts.

Step 5

Test the same domain through another known-good IP if available.

Step 6

Test another known-good domain through the original IP if available.

Step 7

Test your strongest recipient segment.

Step 8

Introduce HTML.

Step 9

Introduce the destination URL.

Step 10

Introduce click tracking.

Step 11

Introduce the complete creative.

Step 12

Expand the recipient segment gradually.

You are progressively answering this question.

"Which variable breaks inboxing?"

That is deliverability troubleshooting.

My Reputation Recovery Priority Order

When things go bad, I usually care about these in roughly this order.

1. Recipient quality
2. Complaints
3. Authentication
4. Domain reputation
5. IP reputation
6. URLs and landing pages
7. Sending velocity
8. Blocklists
9. Tracking infrastructure
10. Message content
11. Platform footprint
12. Technical formatting

The order can change dramatically based on evidence.

If Gmail is literally returning an error saying the IP is on an RBL, investigate the IP first.

Use the evidence in front of you.

Do Not Treat Spam Folder Placement as a Content Problem Automatically

This is another common mistake.

Someone sees spam placement.

Their first reaction is to rewrite the subject line.

Then they remove the word "free."

Then they change the button color.

Meanwhile the sending IP is on Spamhaus.

Or DKIM is broken.

Or the tracking domain is listed.

Or the last mailing generated a disastrous complaint rate.

Content testing has value.

But infrastructure problems need infrastructure fixes.

Do Not Treat Every Problem as an IP Problem Either

The opposite mistake is just as common.

Someone has a perfectly good IP.

Their domain reputation collapses.

They replace the IP.

The new IP works for a few hours or days.

Then placement collapses again.

They replace it again.

Eventually they have burned through an entire range.

The domain followed them everywhere.

Diagnose the identity that is actually causing the problem.

A Reputation Problem Can Live Outside Your Email Domain

Remember the ecosystem.

You can send from this.

newsletter@example.com

Sign with this.

mail.example.com

Track through this.

click.otherdomain.com

Redirect through this.

affiliate-network.example

And finally land here.

landing-page.example

Which domain is "your domain reputation?"

All of them may be relevant in different ways.

This is why modern deliverability work requires looking beyond the From address.

One Bad Shared Asset Can Contaminate Multiple Campaigns

Suppose five brands use the same tracking domain.

Four have fantastic data.

One sends garbage.

The shared tracking identity can become a common reputation dependency.

The same applies to shared IPs, bounce domains, redirect services, and other infrastructure.

Shared infrastructure creates efficiency.

It also creates shared risk.

Gmail's Reputation Dashboard Going Away Might Actually Be Good for Operators

I understand why people are upset about losing it.

I liked it too.

But the dashboard encouraged bad habits.

People would look at "High" and conclude everything was fine even when placement was deteriorating.

Or they would see "Low" and immediately replace infrastructure without understanding why.

Google itself says the reputation labels could be misleading because reputation is only one of many deliverability factors.

The better question was never this.

"What color does Google say my reputation is?"

The better question is this.

"What behavior is Gmail observing from my traffic right now?"

That is what you need to learn to measure.

The Real Reputation Dashboard Is Your Traffic

Your best reputation dashboard consists of what your traffic is telling you.

Are messages accepted?

Are they inboxing?

Are recipients opening?

Are humans clicking?

Are people replying?

Are they buying?

Are they unsubscribing?

Are they complaining?

Are addresses bouncing?

Is Gmail slowing you down?

Are you on meaningful blocklists?

Does plain text inbox?

Does the same domain work on another IP?

Does the same IP work with another domain?

Does removing the tracking domain solve the problem?

Those answers are far more actionable than "Medium."

Final Thoughts

Google can take away Domain Reputation.

Google can take away IP Reputation.

They can remove every colorful reputation graph from Postmaster Tools tomorrow.

Your sender reputation will still exist.

Your domain will still have history.

Your IP will still have history.

Your links will still have history.

Your platform will still leave a footprint.

Your recipients will still vote on your mail through their behavior.

Spamhaus will still evaluate domains and IPs.

Gmail will still throttle suspicious traffic.

Bad data will still destroy good infrastructure.

Good engagement will still protect it.

And no amount of SPF, DKIM, DMARC, IP rotation, domain rotation, or creative rewriting can permanently compensate for sending email that recipients consistently demonstrate they do not want.

That is the part of deliverability that has not changed.

The technology has become more complicated.

The visibility has become less convenient.

The reputation systems have become much better at connecting different signals.

But the fundamental equation remains remarkably simple.

Build a recognizable identity.

Send consistently.

Authenticate everything.

Use clean infrastructure.

Protect your domains.

Protect your IPs.

Know every link inside your messages.

Know where those links eventually go.

Understand your sending platform's footprint.

Watch your data quality.

Send your best traffic when reputation weakens.

Do not create fifty domains to solve a problem one good domain could solve.

Do not rotate infrastructure just because you can.

Test one variable at a time.

And above everything else, send email to people who demonstrate that they actually want it.

That is sender reputation.

You just might not get a graph showing it anymore.

The received wisdom in cold-email warmup is that you throw inbox-to-inbox babble at a fresh sender for a few weeks, let Gmail form an opinion, and only then start sending real campaign content. The babble is often template-generated, reply-heavy, and semantically empty. It teaches Gmail that the sender is "conversational" without ever putting real offer copy in front of the classifier.

We wanted to test something more direct. What happens if you skip the babble and warm the domain with real business-opportunity ("bizop") content from day one? In principle, if we warm the classifier on the exact content we intend to send in production, we would arrive at a healthy reputation without ever having to swap in the "real" copy later.

We ran this test through postmasterops.com, on a single Linode IP and a fresh sending domain. The domain is anonymized in this writeup as the test domain.

The setup

The IP and domain were both new; there was no prior reputation to inherit, good or bad.

Google Postmaster reputation trajectory

Postmaster started reporting on the domain on 07-27 and gave us data (with a few skipped days here and there) all the way through today. Domain reputation, day by day:

IP reputation on the sending IP tracked the same curve exactly one day behind the domain grade, ending at BAD from 08-14 onward.

The interesting part of the shape is that first climb. Under continuous bizop content, the domain actually improved from LOW to MEDIUM and held there for four days. Something about the sender identity was earning trust, at least for a moment. Then it slid back down and eventually collapsed.

Gmail acceptance during the same window

Here is where it stops matching the story you'd tell if you looked at Postmaster alone. Daily Gmail consumer sends / bounces / accept rate:

Acceptance held above 99.8% for almost the entire window, with one bad day (08-11: 78.4%, 453 bounces) that looked like it might be the start of something and then wasn't. Even after Postmaster graded the domain BAD on 08-14, individual message acceptance stayed at 99.9%. As of today the domain is at 100% accept on ~1,100 sends per day.

Whatever Postmaster's grading model is scoring, it is not directly gating delivery on this domain. The classifier that decides whether to accept the SMTP transaction is clearly running on different signals than the classifier that assigns the reputation grade you see in Postmaster Tools. In this test they moved in opposite directions for weeks.

The confounders (there are three of them, and they matter enough to make this test inconclusive)

I want to be honest before drawing any conclusions, because there are three variables that moved at roughly the same time as the Postmaster collapse. Any of them could have contributed. Probably all of them did, which is why we don't feel we've earned a real answer here.

Confounder 1 — the final URL landed on Spamhaus mid-test

Our tracking chain was:

email body
    <a href="https://track.<domain>/c/abc123">Learn more</a>
        302 →  the affiliate/offer landing page

The tracking domain itself was clean. It was on our infrastructure, wrapped through nginx, TLS-terminated, no listing exposure. But the final offer URL — the destination after the 302 redirect — got listed on Spamhaus during the test.

Gmail's content classifier is well-documented to follow redirects when scoring messages for reputation. So even though the visible href in the message body was our clean tracking domain, the classifier followed the chain and saw the Spamhaus-listed destination. That is almost certainly counting against us. The question is how much.

We do not have a clean way to isolate this from the content signal. When the Postmaster collapse happened, the URL was on Spamhaus AND the content was pure bizop. Those two variables moved together, and we cannot pull them apart from this run.

Confounder 2 — one day of about 1,000 4xx errors from Gmail

Separately, on one specific day during the test, we saw a burst of roughly 1,000 4xx (transient) errors from Gmail's MX, fleet-wide, not just this domain. This was almost certainly a Gmail-side issue: the errors cleared by the next day and every other domain sending at the same time saw comparable rejections.

But 4xx retries are still visible to Gmail's reputation model. On a domain that was already trending down, adding 1,000 transient failures across a single day accelerates the slide. This one is fully outside our control. It is in the frame anyway.

Confounder 3 — the reputation kept getting worse after the content stopped

This is the one I cannot fully explain. Under a "content is the sole driver" hypothesis, killing the bad content should let the reputation stabilize and eventually recover. Ours got worse in the days after we stopped sending the offending creatives. That does not fit.

It might indicate that Gmail had already committed to a reputation classification and was carrying it forward regardless of what we sent next. It might mean the Spamhaus listing was the dominant signal all along, and cleaning up the content didn't matter because the destination was still poisoning every message that included a link. It might be that Postmaster's grade lags actual signal by so much that we're still seeing the tail of the earlier damage. We do not have a clean way to disaggregate.

What the data unambiguously shows

There are two things we can say with confidence:

1. The Postmaster grade and the delivery gate are decoupled. For almost the entire window Postmaster was flashing red and Gmail was still accepting 99.9% of messages. Whatever Postmaster is measuring (spam-complaint ratio? aggregate content classifier signal? user engagement decay?), it is not the same thing that the SMTP-accept classifier is measuring. If you optimize for one, you are not automatically optimizing for the other.

2. The domain earned a genuine Postmaster grade improvement on bizop content. LOW to MEDIUM over four days of continuous real-content sending is a positive signal. Not something the "content is toxic until you've banked reputation" narrative would predict. Something about the sender identity was accruing trust, at least for a while.

What we cannot say

We cannot say whether the eventual Postmaster collapse was driven by:

• The content itself
• The Spamhaus-listed final URL in the tracking chain
• The 4xx storm
• Some ordering interaction between all three
• Something else we didn't observe

The Spamhaus confounder alone would be enough to void this test as evidence about bizop content warming. The next run has to isolate the URL variable: same content strategy, tracking chain that terminates on a URL with no Spamhaus history and no chance of one appearing mid-test.

What we're doing next

Two things.

The immediate operational move: we are back to babble-first warmup for every new managed sender on postmasterops.com. Not because this test proved babble is better — it did not prove that — but because babble isolates every one of the variables that made this test unreadable. No tracking chain, no offer URL, no content-classification weight, no possibility of a mid-test Spamhaus event on a page we don't control. When we come back to test bizop-first warming, we will do it with those variables held constant.

The next writeup: the babble pattern that works, the specific inbox-to-inbox behaviors we simulate, and the operational signals we use to catch a reputation slide before it turns into a collapse. Postmaster grade alone is not one of them, for the reason this test made obvious.

The test domain is still sending, still at 100% accept, still graded BAD in Postmaster. It is a good live example of the disconnect. If you want the short version of the lesson from this run: your delivery number and your Postmaster grade are not the same signal, and you should not stop watching either one just because the other one looks green.

The code. Every config file described here lives in one repo, ready to clone: github.com/mattnovakemail/minibook-x-hyprland.

The machine

This writeup is specific to one laptop. Most of what follows is driven by its particular quirks — a rotated DSI panel, an extremely dense screen, a 6 W CPU, and firmware that blocks hibernation — so here it is in full:

Two details from that table cause more trouble than the rest combined.

The panel is 2.25× denser than a normal display. A conventional desktop monitor is around 96 DPI; this one is 216. Anything rendered 1:1 comes out roughly half the size it should be. That single number explains the unreadable Firefox, the 24-point terminal font, and an entire section of scaling work below.

The CPU is a 6 W part. The N150 is genuinely capable for its class, but it has no thermal headroom to waste. That drives the choice of hardware video encoding, the power tuning, and the decision to shell into a bigger machine for compilation rather than build locally.

A note on the RAM figure, since it looks inconsistent: dmidecode reports 4 × 3 GB = 12 GB installed, while /proc/meminfo shows MemTotal: 11986544 kB ≈ 11.4 GiB. The difference is firmware reservation — normal, and not a fault. It's a 12 GB machine.

The starting point

Debian 13 was installed — deliberately minimal. At the installer's software selection step only standard system utilities and SSH server were ticked; every desktop task was left unchecked. The disk was set up with the installer's guided encrypted LVM option, so root and swap both sit inside LUKS. Hyprland had been installed from backports, and that was about it.

The entire Hyprland config was thirteen lines. This is the starting state — the finished version is reproduced in full at the end of this post:

monitor = DSI-1, preferred, auto, 1, transform, 3

$mod = SUPER

exec-once = waybar
exec-once = mako

input {
	kb_layout = us

	touchpad {
		natural_scroll = true
		tap-to-click = true
	}
}

general {
	gaps_in = 3
	gaps_out = 5
	border_size = 2
}

decoration {
	rounding = 6
}

bind = $mod, Return, exec, foot

One keybinding. You could open a terminal. You could not close a window, move one, switch workspaces, take a screenshot, lock the screen, or quit the compositor. Waybar was listed in exec-once but had no config file at all.

The goal was a complete daily-driver desktop, tuned for battery life, on a machine intended mostly for SSH-ing into a beefier build box, taking screenshots, and light development.

What follows is everything that got built, and — more usefully — everything that broke along the way. The interesting through-line turned out not to be the configuration. It was this:

Almost every bug in this stack failed silently. Not one of them printed an error where anyone would look. A keybinding that did nothing. A stylesheet that vanished. Icons that rendered as blank space. A wallpaper daemon that logged one cryptic line and gave up. Precision that was invented out of thin air. The work wasn't writing config — it was noticing the absence of things.

Where it started, in numbers

Facts gathered rather than assumed, before changing anything:

• CPU governor: powersave on the intel_pstate driver, EPP at balance_performance
• Idle draw: 3.68 W (0.5 A × 7.36 V), projecting ~7.6 h from full
• Sleep states offered: freeze mem — and, unusually for a recent Intel laptop, mem_sleep offering both [s2idle] and deep. Many Alder Lake-N machines only expose s2idle; this one still has working S3, which turns out to matter a lot
• Nerd Fonts installed: zero
• Display manager: none
• Wi-Fi: a hand-started wpa_supplicant plus dhcpcd, no NetworkManager

Part 1 — The compositor, and a version that moved underneath us

Hyprland 0.55.2 is recent enough that a large amount of community documentation is simply wrong for it. Three concrete breakages surfaced within minutes of writing a normal-looking config.

Window rules changed shape entirely

The syntax everyone writes:

windowrule = float, class:^(pavucontrol)$

produces, in 0.55:

Config error: invalid field float: missing a value

The rule system was rebuilt around explicit key/value fields with a match: prefix for the selector. The working form is:

windowrule = float = true, match:class = ^(pavucontrol)$
windowrule = suppress_event = maximize, match:class = .*
windowrule = size = 60% 55%, match:class = ^(foot-float)$

I found this by probing the live compositor with hyprctl keyword windowrule until something returned ok, rather than guessing. The error messages were genuinely helpful here — float = true, class = ... complained about class specifically, which pointed straight at needing match:class.

togglesplit no longer exists

Invalid dispatcher, requested "togglesplit" does not exist

It moved into the layout message system:

bind = $mod, Y, layoutmsg, togglesplit

Similarly, dwindle:pseudotile is gone as a config option (the pseudo dispatcher still exists), and misc:vfr moved to debug:vfr.

Gestures were rewritten

The familiar gestures { workspace_swipe = true } block returns no such option. 0.51 replaced it with a top-level keyword:

gesture = 3, horizontal, workspace
gesture = 4, up, special, magic

The one that parses fine and does nothing

This is the first silent failure of the evening.

workspace = workspace = 1, monitor = DSI-1, persistent = true

hyprctl configerrors returns empty. The rule is accepted. The workspace is never created. I tried every syntax variant I could construct — match:id, bare 1,, with and without a monitor — and eventually spun up a nested Hyprland instance with a throwaway config to test in isolation. None of them work in 0.55.2.

Digging into the binary's strings revealed the internal function ensurePersistentWorkspacesPresent and its failure mode (couldn't resolve monitor for {}, skipping), which suggested the rule needs a monitor — but supplying one changed nothing.

So I deleted the dead configuration rather than leave four lines that look meaningful and aren't. Waybar's own persistent-workspaces setting displays workspaces 1–5 permanently regardless, which is the actual user-visible behaviour anyone wants from that feature.

Lesson: "it parses" and "it works" are unrelated claims. Verify the effect, not the syntax.

What got built

Roughly 80 keybindings, in themed groups:

Plus hardware keys (volume, brightness, mic mute) via wpctl and brightnessctl, and a lid switch binding.

One small thing that mattered on a touchscreen device: the panel is rotated transform 3, but the touchscreen input had no matching transform, so taps landed in the wrong place. Wayland doesn't infer this:

input {
    touchdevice {
        transform = 3
    }
}

Part 2 — The bar, and a font that wasn't there

Waybar was in exec-once but had no config whatsoever, so it was running with compiled-in defaults. Building a real one was straightforward: workspaces, window title, wireplumber volume, backlight, network, battery, clock, tray, all in a Tokyo Night palette.

Then every icon rendered as blank space.

The cause is a naming trap. Debian's fonts-font-awesome package installs a font whose family name is literally FontAwesome — the legacy FA4 family — not Font Awesome 6 Free, which is what every modern config snippet lists. The CSS font stack silently matched nothing and fell through to a font with no glyphs at those codepoints.

Worse, the glyphs I'd chosen weren't all in FA4. U+F5DE (a brightness icon in newer sets) simply doesn't exist there. So I checked coverage directly before picking anything:

fc-list ":charset=f185" family    # → FontAwesome

and rebuilt the icon set from codepoints verified present. The final stack:

font-family: "JetBrains Mono", "FontAwesome", monospace;

The glyphs that vanished in transit

A subtler problem, and one that recurred all evening: three-byte private-use-area characters get stripped when written through certain tooling. Codepoints like U+E0B0 (the powerline separator) and U+E0A0 (the git branch symbol) arrived at the file as empty strings, while four-byte supplementary-plane glyphs like U+F0509 survived intact.

The result is config that looks correct and renders nothing:

[](fg:iris)      # ← there is supposed to be a glyph inside those brackets

The fix is to inject them programmatically rather than typing them:

LCAP = chr(0xe0b6)   #  rounded left cap
s = s.replace('[](fg:iris)', '[%s](fg:iris)' % LCAP)

From that point on, every glyph in this project was written with chr() and then audited by reading the file back and checking that the symbol fields were non-empty. That audit caught two more empty symbols later in the starship config that would otherwise have shipped as blank space.

Part 3 — Screenshots

A small script, ~/.config/scripts/screenshot, wrapping grim and slurp:

• always copies to the clipboard and saves to ~/Pictures/Screenshots
• region uses slurp -d; pressing Escape exits silently rather than erroring
• window reads the focused window's geometry from hyprctl activewindow -j via jq
• --edit opens the capture in swappy for cropping, arrows and redaction before saving

Bound to Super+Shift+S (region), Print (screen), Shift+Print (window), and Super+Ctrl+Shift+S (region with annotation).

Note the window-geometry line, which is the sort of thing that's fragile if you write it with grep and awk:

geom=$(hyprctl activewindow -j | jq -r '"\(.at[0]),\(.at[1]) \(.size[0])x\(.size[1])"')

Part 4 — Lock, idle, wallpaper, clipboard — and more version drift

Four packages: hyprlock, hypridle, hyprpaper, cliphist. Two of them had moved their config format, and both failed quietly.

hyprpaper 0.8.4 removed preload entirely

The universally documented form:

preload = ~/Pictures/wallpaper.png
wallpaper = DSI-1, ~/Pictures/wallpaper.png

produces no error, no warning, and exactly one line of log:

Monitor DSI-1 has no target: no wp will be created

No wallpaper appears. Searching the binary for strings showed preload was absent from it altogether, while monitor, path, fit_mode and order were present — implying a block-structured format. The working config:

splash = false

wallpaper {
	monitor = DSI-1
	path = /home/YOUR-USER/Pictures/wallpaper.png
	fit_mode = cover
}

Also: ~ is not expanded, so paths must be absolute.

hyprlock moved grace out of general

Config error: config option <general:grace> does not exist

In 0.9.5 it's a top-level key. I found this by testing candidate placements against a throwaway config using hyprlock --display no-such-display, which parses the file and then fails to connect — a config check that never locks your screen. That trick was worth its weight later.

There was no wallpaper at all

No image existed on the machine, and neither ImageMagick nor Python's PIL was installed. Rather than pull in a dependency, I generated a 1920×1200 Tokyo Night gradient by writing the PNG by hand — zlib-compressed scanlines, CRC'd chunks, ordered dithering to prevent banding on an 8-bit gradient:

def chunk(tag, data):
    return (struct.pack('>I', len(data)) + tag + data
            + struct.pack('>I', zlib.crc32(tag + data) & 0xffffffff))

png = (b'\x89PNG\r\n\x1a\n'
       + chunk(b'IHDR', struct.pack('>IIBBBBB', W, H, 8, 2, 0, 0, 0))
       + chunk(b'IDAT', zlib.compress(bytes(rows), 9))
       + chunk(b'IEND', b''))

118 KB, no dependencies, and it became the basis for the lock screen and greeter backgrounds too.

Verifying the lock screen safely

Before letting anything auto-lock the machine, two checks:

1. /etc/pam.d/hyprlock exists and includes the login stack — if PAM were misconfigured, the first idle lock would strand the user permanently.
2. A deliberate, timed test-lock to confirm it renders and releases.

Both passed. That second check is also where this post's biggest mistake originates, but that comes later.

Part 5 — The idle ladder incident

This is the most instructive failure of the evening, because nothing was broken. Everything worked exactly as configured. The configuration was just wrong for a human being.

The initial hypridle ladder:

I started it live and moved on without saying the timers were now armed.

Four minutes later, while reading my own summary on screen, the backlight dropped to 10%. On this panel that reads as a dead screen, not a dim one. The reasonable response to a laptop that appears to have died is to switch to a different TTY — which is exactly what happened: Ctrl+Alt+F2, log in, start a second Hyprland session.

The consequences compounded:

1. Two live sessions. The abandoned tty1 session kept running, along with its waybar, mako, hyprpaper — and its hypridle.
2. An abandoned session is permanently idle. Its 30-minute systemctl suspend timer was still counting, and systemctl suspend suspends the whole machine, not a session. It would have fired while the user was working in the new session.
3. Two hypridle daemons were now driving global hardware — one backlight, one DPMS state, one suspend command — from two different idle clocks.

I also discovered I'd left two orphaned nested Hyprland instances running from the persistent-workspace experiment; timeout 12 had sent SIGTERM and they'd survived it, running for seventeen minutes.

The fixes

The immediate hazards were killed with about four minutes to spare before the next session's dim/lock cycle. Then the policy changed:

# 10 min -- dim, but stay clearly readable. Any input restores.
listener {
	timeout = 600
	on-timeout = brightnessctl -s set 30%
	on-resume = brightnessctl -r
}

# 20 min -- screen off
listener {
	timeout = 1200
	on-timeout = hyprctl dispatch dpms off
	on-resume = hyprctl dispatch dpms on
}

# No auto-lock and no auto-suspend. Lock manually with Super+Escape.

30% instead of 10% — dim, never dead-looking. Ten minutes instead of four. No auto-suspend at all.

And a structural fix so this class of problem can't recur:

exec-once = pgrep -x hypridle >/dev/null || hypridle    # singleton: global hardware

hypridle touches global hardware, so it must be a singleton across sessions. Waybar and hyprpaper are legitimately per-session; hypridle is not.

Lessons:

• Never arm timers on someone's live machine without telling them the clock is running.
• A dim that looks like failure is a failure, regardless of intent.
• Daemons that control global hardware need singleton guards, because sessions can and do stack up.
• timeout sending SIGTERM does not guarantee a process dies. Verify.

Part 6 — The binding that did nothing

Super+Shift+S produced no selector, no error, no notification. Nothing.

The binding was registered correctly — hyprctl binds showed mods=65 key=S -> exec screenshot region. The script existed and was executable. Running it by hand worked perfectly.

The environment Hyprland's exec inherits is not your login shell's:

PATH=/usr/local/bin:/usr/bin:/bin:/usr/local/games:/usr/games

No ~/.local/bin. The shell couldn't resolve screenshot, and the exec failed into the void — Hyprland doesn't surface a failed exec anywhere visible.

Every earlier test of mine had passed because I'd been exporting PATH="$HOME/.local/bin:$PATH" in my own shell before running things. I had never once tested the environment the binding runs in.

The fix, belt and braces:

env = PATH,/home/YOUR-USER/.config/scripts:/home/YOUR-USER/.local/bin:/usr/local/bin:/usr/bin:/bin:...
$scripts = /home/YOUR-USER/.config/scripts
bind = $mod SHIFT, S, exec, $scripts/screenshot region

Both the env line and absolute paths, so the bindings work even if the env line is ever lost. Verified by making Hyprland itself report its environment:

hyprctl dispatch exec "sh -c 'echo PATH=$PATH > /tmp/probe.txt'"

Lesson: test in the environment the code will actually run in, not the one that's convenient.

Part 7 — HiDPI: 216 DPI and the scale that fixes everything

Firefox launched with unreadably small UI. The instinct is to hunt for a Firefox font setting. That would have been wrong — the same problem afflicted every GTK app, every dialog, every file picker, because it isn't a font problem at all.

At 216 DPI with no scaling, everything renders at roughly half its intended physical size. That's also why the terminal font had been set to 24pt: at 216 DPI, 24pt lands at a normal-looking ~10.7pt physically.

The fix is compositor scaling:

monitor = DSI-1, preferred, auto, 1.5, transform, 3

Scale 1.5 was chosen deliberately over 1.25, 1.75 and 2.0 because 1920/1.5 = 1280 and 1200/1.5 = 800 are both exact integers. Fractional scales that don't divide evenly (1.75 gives 1097.14 × 685.71) force resampling and soften text. Effective density becomes ~144 DPI.

Then everything already tuned for the unscaled screen had to be rebalanced so it stayed the same physical size:

Both running apps reported xwayland=false, so they scale natively rather than going through XWayland's blurry path.

The 25-second bar

After the reboot that followed, waybar took 25 seconds to appear. Its log:

[info] Unable to receive desktop appearance: Timeout was reached

Waybar asks the XDG desktop portal for the light/dark preference at startup and waits out a full D-Bus timeout when nobody answers.

Nobody answered because xdg-desktop-portal-gtk had failed to start, and it had failed because the systemd user manager outlives individual login sessions and was still advertising WAYLAND_DISPLAY=wayland-1 — the display of the session that got abandoned during the idle incident. The GTK portal started, couldn't reach a display that no longer existed, and exited 1.

exec-once = dbus-update-activation-environment --systemd WAYLAND_DISPLAY XDG_CURRENT_DESKTOP XDG_SESSION_TYPE HYPRLAND_INSTANCE_SIGNATURE
exec-once = systemctl --user restart xdg-desktop-portal-gtk.service

Startup went from 25 seconds to 1 second. The same fix repairs file-picker dialogs and screen sharing, which route through the identical portal and were broken in exactly the same way.

Part 8 — Battery

Baseline: 3.68 W idle, projecting ~7.6 hours from full. Decent for an N150 — but several cheap wins were sitting unclaimed.

Energy performance preference. intel_pstate was at balance_performance. A systemd oneshot pins it:

ExecStart=/bin/sh -c 'for f in /sys/devices/system/cpu/cpu*/cpufreq/energy_performance_preference; do echo power > "$f"; done'

Bluetooth was running with zero paired devices — a daemon and a radio powered for nothing. Disabled.

thermald wasn't installed. On a 6 W part, Intel's thermal daemon is worth having.

powertop was installed but nothing ran --auto-tune at boot. Now a oneshot unit does, and I verified afterwards that the touchpad, keyboards and touchscreen were all still enumerated — powertop's aggressive runtime PM has a reputation for breaking input devices.

Wi-Fi power saving was off; a unit enables it via iw.

Result: 3.68 W → 3.57 W, plus a much lower-power sleep state (below).

Part 9 — The network, and the worst mistake of the evening

The machine's Wi-Fi was managed by a hand-started wpa_supplicant plus a hand-started dhcpcd — no NetworkManager, no nmtui, no roaming, and the waybar network module's click action pointed at nmtui, which wasn't installed. Another silent no-op.

I decided to migrate to NetworkManager, and got two things badly wrong.

Mistake one: reading a permission error as an empty file

cat /etc/network/interfaces    # printed nothing

I concluded the file was empty and announced that the Wi-Fi config wasn't persistent and wouldn't survive a reboot. In fact the file is 363 bytes, mode 0600 — the cat had failed with permission denied, and I'd read the empty output as an empty file. The user's reboot disproved me directly.

Worse, that file contained the PSK. Reading it properly would have let me configure NetworkManager non-interactively from the start, without ever needing to ask for a password.

Mistake two: a teardown with no completion guarantee

The migration ran as a plain foreground command:

pkill -f 'wpa_supplicant ...'
pkill dhcpcd
systemctl enable --now NetworkManager    # ← never reached

The command was interrupted between the pkill and the enable. The old stack was dead; the new one had never started. The user came back from a shower to a machine with no networking, and after a suspend/resume cycle it still had none — because nothing was left running to restore it.

The fix: make it atomic and self-healing

The rewritten migration is a script that cannot leave a half-state:

1. Read SSID and PSK from /etc/network/interfaces
2. Write the NetworkManager profile first, before touching anything
3. Comment the interface out of ifupdown's control
4. Stop the old stack
5. Start NetworkManager
6. Poll for up to 60 s for genuine connectivity — an IP and a successful ping
7. On failure, roll back automatically: restore the backup, restart ifup@, and report

It also logs to /var/log/net-switch.log so a failure is diagnosable rather than mysterious. It ran clean: SWITCH-OK, same IP, and it survived a suspend/resume intact.

Lessons:

• A silent command failure and an empty result look identical. Check exit status, or run privileged reads privileged.
• Any operation that dismantles working infrastructure before building its replacement must be atomic and must roll itself back. "I'll just run these four commands" is not a plan.

Part 10 — Sleep: measuring instead of guessing

The direct question was: what happens when I close the lid — will suspend break this machine?

Rather than opine, I wrote a test script that suspends via rtcwake with a hardware timer wake, so the machine returns on its own even if the resume path is completely broken, and logs everything before sleeping so a non-returning machine still leaves evidence.

First result: it works, but the test was worthless

rtcwake rc=0  asleep for 5s (asked for 20s)
battery before: 22%   battery after: 23%

Suspend and resume worked — clean resume, network intact, no hang. But the battery went up: the machine was on AC, so the drain figure measured nothing. And it slept for 3.3 seconds instead of 20, because charging generates a constant stream of EC events, any of which can wake an s2idle system.

Second result, on battery, and a lesson in fake precision

Ten minutes in each state:

The script had confidently printed "5.98 %/hour". That number is fabricated precision, and I'd written the code that produced it.

This battery reports charge_now in 38000 µAh quanta — exactly 1%. Every reading in both tests is a multiple of it: 950000, 912000, 874000, 836000. A ten-minute test that consumes one step tells you the true rate is somewhere around 3–12 %/hour. It does not tell you 5.98.

The script now reports step counts and an explicit quantisation range:

drain: 38000 uAh over 602s = 1 reporting step(s)
       midpoint 227 mAh/h (6.0 %/h, ~17h from full)
       range    0.0-12.0 %/h  <- quantisation, not noise
       only 1 step(s) resolved; test 3-4x longer for a firm number

The comparison still stands on its own: same duration, same conditions, one state consumed a measurable step and the other didn't. deep wins unambiguously, even without a precise ratio.

Making it permanent, without touching the bootloader

I had earlier described switching to S3 as a kernel-commandline change requiring a GRUB edit and a reboot. That was wrong: /sys/power/mem_sleep is writable at runtime. So the whole thing is a sysfs write:

ExecStart=/bin/sh -c 'grep -qw deep /sys/power/mem_sleep && echo deep > /sys/power/mem_sleep'

Same effect as mem_sleep_default=deep, no bootloader risk, and systemctl disable mem-sleep-deep fully reverts it.

Hibernate: blocked, and I got this wrong first

I initially reported hibernate as "95% configured, needs testing not building", pointing at the correctly-sized 11.7 GB encrypted swap and the RESUME= entry already present in the initramfs.

Then I actually looked at /sys/power/state:

freeze mem

No disk. Hibernation is unavailable. The reason:

lockdown:   none [integrity] confidentiality
secureboot: SecureBoot enabled

Secure Boot puts the kernel in integrity lockdown, which disables hibernation outright — regardless of CONFIG_HIBERNATION=y, swap sizing, or resume configuration. The kernel refuses because it can't verify the resume image hasn't been tampered with.

Everything I'd said about the storage side was correct. I simply hadn't checked the one thing that actually gated it. With S3 now working, hibernate's advantage shrank enough that keeping Secure Boot is the better trade.

Part 11 — A graphical greeter

There was no display manager at all. Login was a text console, after which Hyprland had to be started by hand.

The chosen stack: greetd → Hyprland (minimal) → gtkgreet.

Running gtkgreet inside a tiny Hyprland instance rather than under cage is deliberate: this panel needs transform 3 and scale 1.5, and cage can't rotate an output. A greeter compositor config solves it in two lines:

monitor = DSI-1, preferred, auto, 1.5, transform, 3
exec-once = gtkgreet -l -b /usr/share/backgrounds/login.png -s /etc/greetd/gtkgreet.css -c start-hyprland; hyprctl dispatch exit

greetd is deliberately on VT 7, leaving tty1–6 as plain console logins — the escape hatch if the greeter ever fails.

Hardening before shipping something unverified

I could not fully verify the greeter before the user rebooted: their live Hyprland session held DRM master, so the greeter's compositor could never acquire the display while it was running.

Shipping something unverified means hardening the failure path. greetd ships Restart=always with RestartSec=1, so a broken greeter would respawn every second, seizing VT 7 each time and making it genuinely difficult to reach a console. A drop-in caps it:

[Unit]
StartLimitIntervalSec=60
StartLimitBurst=3

Three failures in sixty seconds and it gives up, leaving you on a TTY.

Two bugs found by looking

The greeter user got no groups. This:

usermod -aG video,input,render,seat _greetd

failed entirely because the seat group doesn't exist on this system — usermod aborts the whole call rather than adding the three valid groups. It had to be split into separate invocations. A greeter with no video group cannot open the DRM device.

The wallpaper was unreachable. A home directory is drwx------, so _greetd could never have read a background from the user's home. The image had to go to /usr/share/backgrounds/.

GTK CSS silently discarding the entire stylesheet

Styling gtkgreet, I squeezed the form inward with:

box#body {
    margin-left: 34%;
    margin-right: 34%;
}

The greeter rendered in default GTK — stock blue button, wrong fonts, nothing themed. Not partially styled. Entirely unstyled.

Theme parsing error: gtkgreet.css:23:19: Junk at end of value for margin-left
style loading failed: gtkgreet.css:23:19

GTK CSS does not support percentage margins, and a single invalid declaration causes GTK to discard the whole stylesheet. One bad line, and every rule in the file evaporates.

This is the same failure shape as the empty icons and the unresolvable PATH: the system does exactly nothing, and the nothing looks like a design choice. Every render after that checked for style loading failed explicitly.

The error that flashed at boot

The greeter came up on the first real reboot — with something flashing briefly in the top-right. That's Hyprland's error overlay, and the cause:

WARNING: Hyprland is being launched without start-hyprland. This is highly advised against.

greetd was invoking Hyprland directly rather than the start-hyprland watchdog wrapper. The fix passes the config through the wrapper:

command = "start-hyprland -- --config /etc/greetd/hyprland.conf"

I had that exact warning in my very first nested test log and dismissed the neighbouring line — Creating the Error Overlay! — as routine object construction. It wasn't routine. The overlay was being built because of that warning. A user glancing at their screen for one second found what I'd had in a log file and misread.

Part 12 — Typography and a prompt

The font

The machine had zero Nerd Fonts — only legacy FontAwesome and plain JetBrains Mono. Four styles of MesloLGS NF went into ~/.local/share/fonts (user-level, no root).

Rather than replace the typeface, foot uses a fallback chain:

font=MesloLGS NF:size=16, JetBrains Mono:size=16

foot falls through to later fonts for missing glyphs, so text renders in the primary face and only icons come from the fallback.

The prompt

Starship, two lines, self-contained "pills", Tokyo Night, rendering in 27 ms:

 󰊠  …/demo    master 󰋗1   󰎙 v20.19.2   󱎫 45s
→ npm test

The first version was a continuous powerline chain. It looked good in a git repo, and left two orphaned arrows dangling in a plain directory, because chained background colours assume every segment renders. Self-contained pills — each with its own rounded caps — degrade correctly in every case. Tested across plain directory, clean repo, dirty repo, and repo-with-node.

Two other decisions:

• right_format doesn't work in bash at all (fish/zsh/nushell only). I'd written battery and clock into it before checking. They were dropped rather than faked with $fill — waybar already shows both, and at 24pt there are only ~50 columns in a half-tiled window.
• Segments appear only when relevant: git pill only in a repo, language pill only in a project, duration only past 2 s, exit code only on failure.

Finding a glyph, properly

Asked for a ghost icon, I guessed six codepoints and rendered them at 30pt. They turned out to be a gift box, the Dropbox logo, an image placeholder, a keyboard, a fishhook and a lightning bolt. F02A1, which I'd tried, is one past the real ghost.

So I stopped guessing and fetched the authoritative mapping:

curl -fsSL https://raw.githubusercontent.com/ryanoasis/nerd-fonts/master/glyphnames.json

Eight glyphs match "ghost". Rendering them revealed two more traps: nf-dev-ghost is the Ghost blogging platform wordmark, and nf-fa-ghost (U+EEFE) isn't present in MesloLGS NF at all — it renders as a tofu box. That one would have shipped as an empty rectangle on the strength of its name.

The winner: nf-md-ghost, U+F02A0.

Part 13 — The launcher, and matching the lock screen to it

fuzzel

Super+D had no configuration. It now has a translucent #1a1b26 panel, a 2px iris border with 14px radius, MesloLGS NF, Adwaita app icons, and a magnifier prompt glyph.

Two settings matter beyond looks:

dpi-aware=no      # scale with the compositor's 1.5x, don't compute our own DPI
match-mode=fzf    # subsequence matching: "tgd" finds Telegram Desktop

The first render used selection=2f3549, which was almost indistinguishable from the 1a1b26 background — the highlighted row was effectively invisible. 3b4261 matches waybar's hover state and reads clearly. That's the kind of thing only a screenshot tells you.

hyprlock, and a measurement that overturned an assumption

Restyling the lock screen to match used hyprlock's shape element to draw the same panel.

The first attempt came out visibly undersized. Measuring the screenshot explained why: a panel declared 440 wide rendered 440 physical pixels on a 1920-pixel screen. hyprlock draws in physical pixels and ignores the compositor's 1.5 scale — unlike fuzzel, waybar, and every normal Wayland client. Every dimension in that config is therefore ~1.5× its equivalent elsewhere, and the file says so in a comment so the next person doesn't have to rediscover it.

Final panel: 780×430, chosen to match fuzzel's measured ~787 px width so the two read as one design.

Part 14 — Lockdead

The worst outage of the evening, and entirely self-inflicted.

To preview the restyled lock screen I ran, twice in quick succession:

setsid timeout -s TERM 15 hyprlock --grace 0 &

hyprlock's own log tells the whole story:

Locking session
onLockFinished called. Seems we got yeeten. Is another lockscreen running?
corrupted double-linked list (not small)

A second hyprlock started while the first still held the session lock. Wayland refused it, and it then hit heap corruption and aborted while the session was locked. When a session locker dies without releasing the lock, the compositor deliberately stays locked — a security property, not a bug. The screen was stuck with no locker. The user had to power-cycle.

Three fixes

1. Stop testing that way. SIGTERM-ing a session locker was never safe. Previews now happen inside a nested Hyprland instance, which has its own session lock and cannot touch the real one. For a true-scale preview, the real monitor can be dropped to scale 1.0 briefly so a fullscreen nested compositor is genuinely 1920×1200 — reversible with a single hyprctl reload.

2. Make lockdead recoverable.

misc {
    allow_session_lock_restore = true
}

A freshly launched hyprlock can now adopt an orphaned lock instead of requiring a reboot. Recovery is documented in the keybinding cheatsheet: Ctrl+Alt+F2, log in, hyprctl -i 0 dispatch exec hyprlock.

3. A near-miss worth recording. While cleaning up leftover nested instances I wrote pkill -x Hyprland, which would have killed the user's real session along with the strays. It was blocked before it ran. The correct approach — identifying the nested instance by PID from ps -eo pid,tty,args and killing exactly that — takes ten more seconds and cannot destroy anything.

Earlier in the same session I'd also written pkill -f 'start-hyprland -- --config', which matched its own command line and killed the shell executing it, silently skipping every subsequent step.

pkill with broad patterns is a loaded gun pointed at whatever happens to match, including yourself.

Part 15 — Applications

Thunderbird and Telegram Desktop, with one non-obvious correction.

Telegram is a Qt5 application, and Qt5 defaults to the xcb backend — it would have run through XWayland and looked soft at 1.5 scale, the same class of problem as the tiny Firefox. qtwayland5 was already installed; it just needed telling:

env = QT_QPA_PLATFORM,wayland;xcb

The ;xcb suffix is a deliberate fallback so any Qt app still starts if the Wayland plugin fails, rather than refusing to launch. Verified: xwayland=false on both apps.

They also both opened onto workspace 1, quartering the terminal workspace into 628×374 boxes. On a 1280×800 logical screen that's unusable, so applications got homes:

windowrule = workspace = 2, match:class = ^(firefox|firefox-esr)$
windowrule = workspace = 3, match:class = ^(thunderbird)$
windowrule = workspace = 4, match:class = ^(org\.telegram\.desktop)$

Part 16 — Screen recording

wf-recorder, with two decisions that matter more than usual on this hardware.

Hardware encoding. vainfo reports H.264 and HEVC EncSliceLP — low-power encode — on renderD128. Software-encoding 1920×1200 on a 6 W N150 would have destroyed both framerate and battery:

wf-recorder -c h264_vaapi -d /dev/dri/renderD128 --codec-param=qp=24 -m mp4

Signals, again. wf-recorder must be stopped with SIGINT, not SIGTERM or SIGKILL: it writes the MP4 moov atom on interrupt, and a harder kill leaves an unplayable file. Given how the evening had gone, this was verified rather than assumed — a test capture was parsed for its top-level boxes:

top-level boxes: ['ftyp', 'free', 'mdat', 'moov']
moov present (finalised): True

Recording is a toggle (Super+Alt+R screen, +Shift region, Super+Alt+A with system audio), a red REC pill appears in waybar while active and is hidden otherwise, and the file path lands in the clipboard on stop.

Audio defaults to off, and --audio captures the default sink's .monitor — system audio, what you hear — not the microphone. Mic capture is a separate explicit --mic flag, so nothing records you by accident.

Part 17 — The console, where none of the fonts exist

The prompt looked wrong outside Hyprland. Icons missing, colours flat. The instinct is to install the font on the console too. That instinct is wrong, and usefully so.

The Linux virtual console does not use fontconfig. It loads a PSF font directly into the video hardware, and the format is hard-capped at 512 glyphs. Nerd Font icons live in the Private Use Area — U+E000–U+F8FF and the supplementary block at U+F0000+. They cannot be represented in a console font at all. There is no font you can install that fixes this, because the VT never consults the font system that would find it.

The console also has no truecolor. Hex values like #bb9af7 have nowhere to go; you get the 16 ANSI colours.

So the console gets a different prompt, chosen automatically:

if command -v starship >/dev/null 2>&1; then
    if [ "$TERM" = "linux" ]; then
        export STARSHIP_CONFIG="$HOME/.config/starship-tty.toml"
    fi
    eval "$(starship init bash)"
fi

starship-tty.toml carries the same information with pure ASCII symbols and named ANSI colours — git:main, ~1 ?1 for modified and untracked, node:v20.19.2, > for the character:

user@host .../system git:main ~1 ?1 node:v20.19.2 took 4s !NOTFOUND
>

Rather than squint at it, the check was programmatic — strip the escape sequences and assert that nothing above ASCII survives:

txt = re.sub(r'\x1b\[[0-9;]*m', '', out)
bad = [(c, hex(ord(c))) for c in txt if ord(c) > 127]
#  → NONE

The bigger console problem nobody mentioned

At 216 DPI, the default Fixed 8x16 console font is 5.3 points physically. Not small — unreadable.

That matters more than it sounds, because on this machine the TTY is the documented escape hatch: it is where you go when the greeter fails to start, and where you go to recover a dead lock screen. Twice in one evening it was the recovery path. An escape hatch you cannot read is not an escape hatch.

 8x16 glyph  →  5.3pt physical   unusable
16x32 glyph  → 10.7pt physical   comfortable

Debian ships Terminus at that size, though the filenames are a trap: Lat15-Terminus32x16.psf.gz is 16 wide by 32 tall — the name lists height first. Verified by reading the PSF2 header rather than trusting the ordering:

h = struct.unpack('<I', d[24:28])[0]   # 32
w = struct.unpack('<I', d[28:32])[0]   # 16

FONTFACE="TerminusBold"
FONTSIZE="16x32"

120 × 37 cells on the panel, at a size you can actually read.

And one last silent no-op, right on cue

Applying it:

sudo setupcon --force

Exit status 0. Nothing changed. The cached loader still read:

setfont '/usr/share/consolefonts/Lat15-Fixed16.psf.gz'

with timestamps untouched from that morning's install. --force does not regenerate the cache; setupcon --save --force does. The only way to catch it was to read the generated script and compare file timestamps — the command itself reported success either way.

What was deliberately left broken

The LUKS passphrase prompt at boot is still 8×16, because Debian's console-setup package ships no initramfs hook — the hooks directory has keymap and a pile of cryptroot scripts, but nothing for the font. Getting a console font into the initramfs means hand-writing a hook, and on a machine that boots from an encrypted root, a broken initramfs hook is an unbootable machine.

A larger password prompt is not worth that risk. Documented as a known limitation instead of quietly attempted.

Part 18 — Files: one need that was already met, one that wasn't

Two requirements that sound like the same thing and aren't: a working file picker for browser uploads, and something to browse files in.

The picker needed nothing at all

The instinct is to install a file manager so the browser has something to open. That is not how it works. Firefox and Chromium get their upload dialog from GTK, or from the XDG desktop portal — org.freedesktop.portal.FileChooser, implemented here by xdg-desktop-portal-gtk. No file manager is involved.

Rather than assume it worked, the exact call the browser makes was invoked directly over D-Bus:

gdbus call --session \
  --dest org.freedesktop.portal.Desktop \
  --object-path /org/freedesktop/portal/desktop \
  --method org.freedesktop.portal.FileChooser.OpenFile \
  "" "Upload a file" "{}"

A real dialog appeared — Wayland-native, dark-themed, with Recent / Home / Other Locations. Nothing to install.

Worth noting why it worked, because it very nearly didn't: this is the same portal stack that was silently broken earlier by a stale WAYLAND_DISPLAY in the systemd user environment. The dbus-update-activation-environment fix that took waybar's startup from 25 seconds to 1 also repaired file pickers and screen sharing, which route through the identical backend. One environment variable, three unrelated-looking symptoms.

The browser: pcmanfm, and two silent config traps

For actually browsing files with image previews, the candidates by installed footprint:

Thunar is nominally smaller than pcmanfm but drags in twenty XFCE dependencies. pcmanfm won on total weight.

On previews specifically: no lightweight GTK file manager has a hover-preview pane. What pcmanfm does instead is better in practice — persistent thumbnails in thumbnail view, so every image in a directory shows its content at once rather than one at a time under the cursor.

Getting those thumbnails working took two corrections, both silent, both mine.

Keys in the wrong section are discarded without a word. I wrote thumbnail_local and thumbnail_max under [ui]. libfm expects them in [config]. The size key is thumbnail_size, not thumbnail_icon_size. First launch showed generic mimetype icons, no error, no warning, empty thumbnail cache. The only way I found the correct names was to read the file pcmanfm itself had rewritten, which spelled out the schema it actually uses.

The config file is autogenerated and overwritten on exit:

# Configuration file for the libfm version 1.4.0.
# Autogenerated file, don't edit, your changes will be overwritten.

My first edit was reverted the instant pcmanfm launched. It has to be written while pcmanfm is not running — which is a rule the file politely states and which is very easy to skim past.

One more default worth changing: thumbnail_max=2048 is a size cap in KB. Images larger than 2 MB silently get no thumbnail. Current screenshots are ~200 KB so it wasn't the blocker, but a photo or a full-resolution capture would have quietly lost its preview later. Set to 0 for no limit.

[config]
thumbnail_local=1
thumbnail_max=0

[ui]
thumbnail_size=160
show_thumbnail=1

Bound to Super+E, and registered as the inode/directory handler so "open containing folder" works from other applications.

Part 19 — Camera and microphone, and 60 dB of stacked gain

"Does the webcam work?" is a question with two very different answers: does the device enumerate, and does it produce usable output. Only the second one matters before a video call, and only the second one requires actually capturing something.

The camera enumerated, then proved itself

/dev/video0, /dev/video1, /dev/media0
uvcvideo loaded
Hy-Usb2.0-1*MIC: Hy-UXGA(8101)-   1600x1200 / 960x720 / 640x480

Enumeration is not evidence. The real test is a frame:

v4l2-ctl -d /dev/video0 --stream-mmap --stream-count=1 --stream-to=frame.raw

168 KB for a 1600×1200 capture is far too small for raw YUYV (which would be 3.8 MB), so it should be MJPEG — confirmed by the magic bytes:

d[:2] == b'\xff\xd8'   # → JPEG

A real, compressed, correctly-sized image. That's the camera working.

I deliberately did not open the file. Format, size and a successful capture prove the device works; the contents are a photograph of somebody's room. Verification does not require looking at it, and it was deleted along with the audio test.

The microphone "worked" and was completely unusable

The first recording captured audio on the first try. It was also garbage:

6.0s   peak 0.00000 dBFS   rms -1.3 dBFS
non-zero samples: 285689/285696  (100.0%)

A microphone in a quiet room does not produce an RMS of −1.3 dBFS. That is a saturated square wave — the input pegged against the rail for six solid seconds. "The mic works" and "the mic is usable on a call" were, again, unrelated claims.

The codec's mixer explained it immediately:

Capture            63/63  [100%]  [+30.00 dB]
Internal Mic Boost  3/3   [100%]  [+30.00 dB]

Sixty decibels of gain stacked on an internal microphone. Two independent controls, each at maximum, each contributing +30 dB. Nothing warns you; the device simply reports beautifully loud audio that happens to be clipped beyond recognition.

Dropping Internal Mic Boost to 0 dB and the PipeWire source to 40%:

peak -0.3 dBFS   rms -17.6 dBFS   clipped samples: 0

Persisted with alsactl store so it survives reboots.

The measurement that nearly went wrong

My second attempt still showed clipping, and the obvious move was to keep cutting gain until it stopped. That would have been wrong.

wpctl status showed a live stream:

Streams:
    66. Firefox
         68. output_FL  > ALC269VC Analog:playback_FL  [active]

Firefox was playing audio through the speakers, and the microphone was faithfully recording it. I was about to tune a microphone against the machine's own output. Muting the sink for the duration of the measurement — and unmuting afterwards — isolated the actual room:

wpctl set-mute @DEFAULT_AUDIO_SINK@ 1
#   ... record ...
wpctl set-mute @DEFAULT_AUDIO_SINK@ 0

The lesson generalises well beyond audio: before tuning against a measurement, check what else is feeding into it.

The device name that lies

The USB module identifies itself as Hy-Usb2.0-1*MIC, which reads unambiguously as "this is where the microphone is". It is not:

Port 005: Dev 002, If 0, Class=Video, Driver=uvcvideo
Port 005: Dev 002, If 1, Class=Video, Driver=uvcvideo

Two interfaces, both Video. No USB audio class interface at all, and /proc/asound/cards lists exactly one card — the Intel HDA codec. The microphone is the built-in analog input; the camera module has no microphone despite its name. Worth knowing before hunting for a device in a conferencing app's dropdown that does not exist.

For video calls specifically

Camera access in Firefox and Chromium goes straight through V4L2 — no portal involved, and the user needs to be in the video group (or hold the logind ACL). Screen sharing does go through the portal, which means xdg-desktop-portal-hyprland has to be alive — the same portal stack that serves file pickers, and the same one that was silently dead earlier over a stale WAYLAND_DISPLAY.

Final advice worth writing down: after setting levels by measurement, confirm them with the conferencing app's own audio test and its live level meter. A number that looks right for room noise still has to be right for a speaking voice, and that is not something a script can measure for you.

Part 20 — The small pieces that make it a daily driver

Not everything worth doing needs a section of its own. These are the pieces that turn a configured compositor into a machine you actually work on.

Remote development, on a laptop that suspends

This machine is not for compiling. It is for shelling into something that is. That changes which tools matter.

mosh is the important one, and the reason is specific to a laptop: an SSH session dies when the machine suspends or changes network. Close the lid, walk to a café, open it — the SSH connection is gone and whatever it was running went with it. mosh survives both suspend and roaming, reconnects silently, and keeps local echo responsive over bad links. Paired with tmux on the remote end, closing the lid mid-build costs nothing.

The SSH config is tuned for the same reality:

Host *
    ServerAliveInterval 20
    ServerAliveCountMax 3
    TCPKeepAlive no
    ControlMaster auto
    ControlPath ~/.ssh/cm-%r@%h:%p
    ControlPersist 10m
    AddKeysToAgent yes
    IdentityFile ~/.ssh/id_ed25519

ServerAliveInterval with a low count means dead connections fail fast instead of hanging for minutes after a resume. ControlMaster with ControlPersist 10m multiplexes subsequent connections over the first one, so the second and third ssh to the same host are instant — noticeable on a machine where you open a lot of short-lived sessions.

Default applications, so things open where you expect

A desktop without mime associations is a desktop where double-clicking does nothing. The set here is deliberately minimal — one lightweight tool per type:

[Default Applications]
inode/directory=pcmanfm.desktop
image/png=imv.desktop
image/jpeg=imv.desktop
application/pdf=org.pwmt.zathura.desktop
text/html=firefox-esr.desktop
x-scheme-handler/https=firefox-esr.desktop

imv is a Wayland-native image viewer, zathura a keyboard-driven PDF reader. Both are small, both start instantly, and neither pulls in a desktop environment. This matters more than it sounds on a screenshot-heavy workflow: the screenshot tool saves a file, and you want looking at it to be free.

Clipboard history

cliphist with two watchers — one for text, one for images:

exec-once = pgrep -f "type text --watch cliphist" >/dev/null || wl-paste --type text --watch cliphist store
exec-once = pgrep -f "type image --watch cliphist" >/dev/null || wl-paste --type image --watch cliphist store

Super+Shift+V pipes the history through fuzzel and copies the selection back. Image entries are stored too, which pairs neatly with a screenshot tool that always copies to the clipboard — the last several screenshots stay retrievable rather than being overwritten by the next Ctrl+C.

The pgrep guards are the same singleton pattern used for hypridle: these are per-user daemons, and a second login session should not start a second copy.

A cheatsheet, because eighty bindings is too many to remember

Super+/ opens a formatted reference in a floating terminal — apps, window management, workspaces, screenshots, recording, clipboard, and the recovery steps for a hung lock screen. It is a shell script with printf, which means it costs nothing and cannot itself break.

Everything in version control

All of it lives in a git repo in ~/.config, including copies of the files that live outside it — the four custom systemd units, the greeter config in /etc/greetd, ~/.bashrc and ~/.profile, and /etc/default/console-setup — each with a README noting the live path, since editing the copy does nothing.

Fifteen commits, each one explaining why rather than what. That matters more than usual here, because a surprising amount of this configuration looks arbitrary until you know which silent failure it exists to prevent.

MiniBook X quirks worth knowing

Things specific to this hardware that cost time, and that anyone else running Linux on an N150 MiniBook X will meet.

The panel is mounted rotated

The DSI panel is physically 1200×1920 portrait, mounted sideways. Everything must be rotated in software:

monitor = DSI-1, preferred, auto, 1.5, transform, 3

The kernel console needs telling separately — this machine already had fbcon=rotate:1 on the kernel command line, which is why the boot text and TTYs are the right way up. Without it, your escape hatch is sideways.

The touchscreen does not inherit the rotation. Wayland won't infer it, so taps land in the wrong place until you match the transform explicitly:

input {
    touchdevice {
        transform = 3
    }
}

Any greeter or lock screen also needs its own rotation, which is why the greeter here runs gtkgreet inside a minimal Hyprland rather than under cage — cage can't rotate an output.

Goodix touchscreen throws an i2c error on every resume

Goodix-TS i2c-GDIX1002:00: Error reading 1 bytes from 0x8047: -121

-121 is EREMOTEIO, and it fires on every wake from suspend. It looks alarming in dmesg --level=err and it is entirely cosmetic: the device never re-probes, stays registered on the same input node, and touch works normally afterwards. Verified by resuming and using it.

DSI link not ready on resume, and atomic-update warnings in normal use

i915 0000:00:02.0: [drm] *ERROR* DSI link not ready
i915 0000:00:02.0: [drm] *ERROR* Atomic update failure on pipe A ...

Both are logged at error level and neither indicates a real fault. Check the uptime stamps: the atomic-update messages appear mid-session, nowhere near a suspend, so they're routine scanline-timing warnings on a DSI panel. The link message appears at resume and the display recovers immediately.

The internal microphone ships with +60 dB of gain

Out of the box, the ALC269VC codec has both capture controls at maximum:

Capture            63/63  [+30.00 dB]
Internal Mic Boost  3/3   [+30.00 dB]

The result is audio clipped into a square wave — it records, and it is unusable on a call. Fix, then persist it:

amixer -c 0 sset "Internal Mic Boost" 0
wpctl set-volume @DEFAULT_AUDIO_SOURCE@ 0.40
sudo alsactl store

The camera module is named "MIC" and has no microphone

The webcam enumerates as Hy-Usb2.0-1*MIC, which reads like a combined camera-and-microphone device. lsusb -t shows two interfaces, both Class=Video, and /proc/asound/cards lists only the Intel HDA codec. There is no camera-side microphone. The camera itself is fine: MJPEG at 1600×1200, 960×720 and 640×480.

The firmware has broken ACPI tables

Every boot logs exactly six ACPI errors:

ACPI BIOS Error (bug): Failure creating named object [\_SB.PC00.RP09.PXSX._DSD], AE_ALREADY_EXISTS
ACPI BIOS Error (bug): Could not resolve symbol [\_SB.PC00.TXHC.RHUB.SS01], AE_NOT_FOUND
Bluetooth: hci0: No support for _PRR ACPI method

Six on this boot, six on the previous, six on the one before. They are CHUWI firmware bugs, they are harmless, and they will alarm you if you go looking at journalctl -p 3 for the first time after changing something. Count them across boots before blaming your own work.

The firmware refuses Secure Boot dbx updates

fwupd offers a Microsoft UEFI revocation-database update and then reports:

Update Error: System firmware cannot accept DBX updates

So there is effectively nothing installable via fwupd on this machine. Worth setting up anyway, but don't expect it to do anything.

Secure Boot blocks hibernation

lockdown:   none [integrity] confidentiality
secureboot: SecureBoot enabled

Secure Boot puts the kernel in integrity lockdown, and lockdown disables hibernation outright. /sys/power/state shows freeze mem with no disk, no matter how correctly your swap is sized or how carefully RESUME= is set in the initramfs. Your options are to disable Secure Boot in firmware or to do without hibernate.

But S3 deep sleep does work — and it's worth switching to

This is the good news, and it's unusual for a recent Intel laptop:

/sys/power/mem_sleep:  [s2idle] deep

deep is offered and functional. Measured over ten minutes each on battery, s2idle consumed a full 1% battery step while deep stayed below the measurement floor entirely. Since /sys/power/mem_sleep is writable at runtime, switching needs no bootloader edit at all:

ExecStart=/bin/sh -c 'grep -qw deep /sys/power/mem_sleep && echo deep > /sys/power/mem_sleep'

With hibernate unavailable, this is the single most valuable power change on the machine.

Battery reports charge in 1% quanta

charge_now on this battery only moves in 38000 µAh steps — exactly 1% of its 3800 mAh design capacity. Any drain measurement shorter than an hour resolves one or two steps and cannot support more than one significant figure. Do not let a script print you "5.98 %/hour" from a ten-minute sample; it is arithmetic, not measurement.

The N150 has hardware video encoding — use it

VAProfileH264Main:  VAEntrypointEncSliceLP
VAProfileHEVCMain:  VAEntrypointEncSliceLP

EncSliceLP is Intel's low-power encode path, available on /dev/dri/renderD128 once intel-media-va-driver is installed. On a 6 W part, software-encoding a 1920×1200 screen recording is not viable; VAAPI is close to free.

The machine itself: worth it

This post is a long list of things that broke, so it would be easy to come away with the wrong impression. Let me correct that, because the MiniBook X is a genuinely excellent little computer and most of the problems above were software drift, not hardware faults.

It is completely silent, and it stays cold. There are zero fans in this chassis — /sys/class/hwmon/*/fan1_input returns nothing to enumerate. Under a load average of ~1.0 with Firefox, Thunderbird and Telegram all running, the package temperature sits at 34 °C against an ambient of 27.8 °C. Six degrees over room temperature. You can work with it on your lap indefinitely, and there is no fan noise because there is no fan.

It is quick in the ways you actually notice. The N150 is a 6 W part, and on paper that sounds like a compromise. In practice: graphical.target is reached 4.3 seconds into userspace, the shell prompt renders in 27 ms, the status bar starts in 1 second, and applications launch without the pause you brace for on low-power hardware. LPDDR5-6400 across two channels is doing real work here — this is not the sluggish Atom experience the "N" prefix might suggest.

The battery genuinely lasts. Measured on battery with the full application stack running: 3.83 W, projecting 7.6 hours from full on a 3800 mAh cell. Idle at the desktop it drops to 3.57 W. And with S3 deep sleep enabled, a closed lid consumed less than the battery's own 1% measurement resolution across ten minutes — you can shut it and walk away without watching the charge evaporate.

The screen is the standout feature. 1920×1200 on a 10.5-inch panel works out to 216 PPI. For context:

It is within four percent of a MacBook Air's density, on a machine that costs a fraction as much. Text at 1.5× scale is genuinely crisp — the entire scaling section of this post exists precisely because the panel is too good to run unscaled. The 3:2 aspect ratio is also the right choice for a small screen: more vertical space for code and documents than a 16:9 panel of the same diagonal.

The build quality is not what the price suggests. Aluminium chassis, a 360° hinge with no flex, a keyboard that is genuinely usable at this size, and a touchscreen that works properly once you tell Wayland the panel is rotated. It feels like a considerably more expensive machine than it is.

So: should you buy one?

Yes — with clear eyes about what you are buying.

The issues catalogued in this post are worth reading before you commit, and they are almost all one-time setup costs rather than daily friction:

• Secure Boot blocks hibernation. S3 deep sleep works, which covers most of the same ground, but you should know before you plan around hibernate.
• The internal microphone ships with +60 dB of stacked gain and must be turned down before it is usable on a call. One command, once.
• The camera module is misleadingly named and has no microphone in it.
• The firmware logs six harmless ACPI errors on every boot and refuses dbx updates.
• The panel is mounted rotated, so anything that draws to the screen — greeter, lock screen, console — needs to be told about it.

None of that is a defect in daily use. Every one of them is a thing you configure once and never think about again. What you get in return is a fanless, silent, genuinely portable machine with a near-Retina screen and seven-plus hours of real battery life, running a full Wayland desktop comfortably on 6 watts.

For SSH-ing into a build box, taking screenshots, writing, and light development — the exact workload this was set up for — it is hard to think of anything better at the price. It is a fantastic little machine and it is well worth what it costs.

What the finished system looks like

~/.config/                          15 commits, 39 tracked files
├── hypr/
│   ├── hyprland.conf               277 lines — compositor, 80+ binds
│   ├── hyprlock.conf               109 lines — lock screen
│   ├── hypridle.conf                28 lines — idle policy
│   └── hyprpaper.conf                     — wallpaper
├── waybar/{config.jsonc,style.css}  bar + Tokyo Night CSS
├── fuzzel/fuzzel.ini                launcher
├── starship.toml                   214 lines — prompt (Nerd Font, truecolor)
├── starship-tty.toml               ASCII/16-colour prompt for the VT
├── foot/foot.ini                    terminal
├── mako/config                      notifications
├── swappy/config                    screenshot annotation
├── pcmanfm/, libfm/                 file manager + thumbnail settings
├── gtk-3.0/, gtk-4.0/               GTK settings (no gsettings on this box)
├── scripts/
│   ├── screenshot                   grim/slurp/swappy → clipboard + file
│   ├── record                       wf-recorder toggle, VAAPI
│   ├── hypr-keys                    keybinding cheatsheet (Super+/)
│   ├── sleep-test.sh                rtcwake harness with honest drain math
│   └── net-switch.sh                atomic ifupdown→NM migration w/ rollback
├── systemd-system/                  copies of 4 custom units, for VCS
├── greetd-system/                   copies of the greeter config, for VCS
├── home-dotfiles/                   copies of ~/.bashrc, ~/.profile
└── etc-console-setup/               copy of /etc/default/console-setup

Custom systemd units: epp-power, powertop, wifi-powersave, mem-sleep-deep.

Measured outcomes: 3.68 W → 3.57 W idle; s2idle → deep (S3) sleep; waybar startup 25 s → 1 s; prompt renders in 27 ms; every application confirmed Wayland-native.

The pattern

Nineteen distinct problems were solved over the course of this build. Almost none of them announced themselves.

• A binding that did nothing, because PATH lacked one directory
• Icons that rendered as blank space, because a font family had a different name than every tutorial claims
• Glyphs stripped to empty strings in transit, twice
• A stylesheet entirely discarded over one unsupported unit
• A wallpaper daemon that logged one line and gave up
• A workspace rule that parses cleanly and does nothing
• A menu item pointing at a program that isn't installed
• A 25-second startup delay caused by a display name from a session that no longer existed
• Fabricated precision from a quantised sensor
• A permission error read as an empty file
• A usermod that added no groups because one name was invalid
• A pkill that killed the shell running it
• A setupcon --force that exited 0 and regenerated nothing
• Config keys placed in the wrong INI section, discarded without comment
• A config file silently overwritten by the program that reads it
• A microphone at +60 dB reporting healthy, fully-clipped audio
• A USB device whose name advertises a microphone it does not have

The tools were not lying. They were saying nothing at all, and nothing is indistinguishable from success until you go looking.

Three habits did most of the work:

Verify the effect, not the syntax. hyprctl configerrors being empty means the parser was satisfied. It says nothing about whether the workspace exists, the wallpaper drew, or the binding fired. Every claim in this post that survived was one where the outcome was observed — a screenshot taken, a process listed, a file's byte structure parsed.

Test in the real environment. The screenshot binding worked every time I tested it, because I was testing in my shell and not in Hyprland's. The greeter's compositor could never be verified while a live session held DRM master. Where the real environment couldn't be reached, the honest move was to say so and harden the failure path instead of claiming success.

When you can see it, look at it. fuzzel, gtkgreet and hyprlock are all Wayland clients that can be screenshotted. Every visual decision here — the invisible selection colour, the crushed background gradient, the orphaned powerline arrows, the undersized lock panel, the fake ghost glyphs — was caught by rendering the thing and looking at it, not by reasoning about the config.

The single most expensive mistake, the lockdead reboot, came from breaking that last rule in the most direct way possible: I tested a lock screen by locking a screen someone was using.

What is still outstanding

In the spirit of the rest of this post, the things that are not done:

There is no off-machine backup. The configuration is in git — fifteen commits — but git remote returns nothing. It lives on exactly one encrypted NVMe. Every silent failure catalogued here was recoverable; a dead disk would not be. This is the highest-value remaining task and it takes about a minute.

No automatic security updates. unattended-upgrades is not installed, on a laptop that roams onto networks it does not control.

No on-screen keyboard, on a 360° convertible. Fold it into tablet mode and there is no way to type — including at the greeter and the lock screen, which would strand you. wvkbd is the Wayland answer, and it needs wiring into hyprlock and gtkgreet specifically, not just the desktop session.

The sleep drain figure is one significant figure at best. Ten-minute samples resolve a single 1% battery step. An hour-long test would give a real number; the comparison between s2idle and deep stands regardless, because both ran under identical conditions.

Secure Boot versus hibernation is an open decision, deliberately left to the owner. With S3 working, the case for disabling Secure Boot is much weaker than it was.

hyprlock looks fragile in this build. It aborted with corrupted double-linked list when a second instance was refused the session lock — and it aborted with the same message during a harmless config parse check with no display attached. It locks and unlocks reliably in normal use, and allow_session_lock_restore now makes a failure recoverable rather than terminal, but it is worth knowing.

The LUKS passphrase prompt is still 8×16. Deliberate: Debian ships no console-setup initramfs hook, and hand-writing one on an encrypted-root machine risks an unbootable system.

Two things were checked and needed nothing: fstrim.timer is enabled and active (correct, given discard on the LUKS volume), and the firmware has no installable updates.

Before you copy anything: what to substitute

Paths and device names in this post are from one machine. Four things need changing, and one of them is not optional.

/home/YOUR-USER appears in hyprland.conf and hyprpaper.conf. These must be absolute paths — Hyprland does not expand $HOME in env = or in $variable definitions, and hyprpaper 0.8.4 does not expand ~ in a wallpaper { path = } block either. That last one fails silently: you get one log line about the monitor having no target, and no wallpaper. Substitute your actual username rather than trying to make ~ work.

(hyprlock.conf is the exception — it does expand ~ in its background path.)

DSI-1 is this panel's output name. It is the same on any MiniBook X, but on other hardware run hyprctl monitors and use whatever Monitor <name> reports.

wlp0s20f3 is this machine's wireless interface, referenced in the wifi-powersave unit. Find yours with ip -br link.

card0 / /dev/dri/renderD128 are the ALSA card index and the DRM render node used in the microphone and screen-recording commands. Both are index 0 on a single-GPU, single-sound-card laptop, which this is; confirm with aplay -l and ls /dev/dri/.

Everything else — usernames in prompt examples, hostnames — is cosmetic.

Appendix — reproducing this from scratch

An ordered runbook. Everything here was done on this machine; the parts that predate the desktop build (the Debian install itself, backports, the console rotation) are included because without them the rest does not work.

1. The Debian install

Debian 13 "trixie", installed from the netinst image. At the software selection step, everything graphical is deselected:

[ ] Debian desktop environment
[ ] ... GNOME / KDE / Xfce / etc
[*] SSH server
[*] standard system utilities

That is the whole point — no display manager, no desktop, no half of GNOME arriving as a dependency. You get a text console and a network stack, and every graphical component that ends up on the machine is one you chose.

For partitioning: Guided — use entire disk and set up encrypted LVM. That produces the layout this machine runs:

nvme0n1
├─nvme0n1p1   976M  vfat         /boot/efi
├─nvme0n1p2   977M  ext4         /boot          (unencrypted; required for LUKS root)
└─nvme0n1p3   475G  crypto_LUKS
  └─nvme0n1p3_crypt  LVM2 volume group "host-vg"
    ├─host--vg-root    463.2G  ext4   /
    └─host--vg-swap_1   11.7G  swap   [SWAP]

/boot has to sit outside the encrypted volume so the bootloader can read a kernel and initramfs; everything else is inside. The resulting crypttab entry matters later:

nvme0n1p3_crypt UUID=... none luks,discard,x-initrd.attach

discard enables TRIM through the LUKS layer (pair it with fstrim.timer, which Debian enables by default), and x-initrd.attach unlocks the volume early — which is what would make hibernate-to-encrypted-swap possible, if Secure Boot were not blocking hibernation.

2. Console rotation, before anything else

This panel is mounted rotated. Until the kernel console is rotated, the text console — your only interface at this point, and your escape hatch forever after — is sideways.

sudo nano /etc/default/grub

GRUB_CMDLINE_LINUX_DEFAULT="quiet fbcon=rotate:1"

sudo update-grub

fbcon=rotate:1 rotates the framebuffer console 90° clockwise. It is independent of anything Wayland does later — Hyprland's transform = 3 handles the graphical session, and this handles TTYs, the GRUB menu's aftermath, and the boot messages.

Reboot and confirm the console is readable before continuing.

3. A readable console font

At 216 DPI the default Fixed 8x16 is 5.3 points. Fix it now, while the console is still the primary interface:

sudo nano /etc/default/console-setup

FONTFACE="TerminusBold"
FONTSIZE="16x32"

sudo setupcon --save --force     # --force alone silently does nothing

4. Enable backports

Hyprland is not in Debian stable:

echo 'deb http://deb.debian.org/debian trixie-backports main' \
    | sudo tee /etc/apt/sources.list.d/trixie-backports.list
sudo apt update

5. Install the compositor and the desktop

hyprland exists only in backports, so it would resolve there on its own. Pass -t trixie-backports anyway: the flag is what allows its dependencies to be satisfied from backports too. mesa, PipeWire, WirePlumber and libxkbcommon all exist in stable at older versions, and without the flag you get a new compositor on an old graphics stack:

sudo apt install -t trixie-backports hyprland xdg-desktop-portal-hyprland

Then everything else — see the install appendix below for the full command and which packages resolve to backports on their own.

6. Group membership

sudo usermod -aG video $USER      # camera and DRM access

Log out and back in for it to take effect. Note that usermod -aG a,b,c aborts entirely if any one group does not exist — issue them separately if unsure.

7. Fonts

mkdir -p ~/.local/share/fonts && cd ~/.local/share/fonts
base=https://github.com/romkatv/powerlevel10k-media/raw/master
for style in Regular Bold Italic "Bold%20Italic"; do
    curl -fsSL "$base/MesloLGS%20NF%20${style}.ttf" \
         -o "MesloLGS NF ${style//%20/ }.ttf"
done
fc-cache -f ~/.local/share/fonts

8. The four systemd units

None of these ship with anything; all are hand-written to /etc/systemd/system/, then sudo systemctl enable --now <name>.

# epp-power.service — intel_pstate energy preference
[Unit]
Description=Set intel_pstate energy_performance_preference to power
After=multi-user.target
[Service]
Type=oneshot
ExecStart=/bin/sh -c 'for f in /sys/devices/system/cpu/cpu*/cpufreq/energy_performance_preference; do echo power > "$f"; done'
RemainAfterExit=yes
[Install]
WantedBy=multi-user.target

# mem-sleep-deep.service — S3 instead of s2idle
[Service]
Type=oneshot
ExecStart=/bin/sh -c 'grep -qw deep /sys/power/mem_sleep && echo deep > /sys/power/mem_sleep'
RemainAfterExit=yes

# wifi-powersave.service
[Service]
Type=oneshot
ExecStart=/usr/sbin/iw dev wlp0s20f3 set power_save on
RemainAfterExit=yes

# powertop.service — runtime PM for PCI/SATA/audio
[Service]
Type=oneshot
ExecStart=/usr/sbin/powertop --auto-tune
RemainAfterExit=yes

Also sudo systemctl disable --now bluetooth if you have no paired devices, and sudo systemctl enable --now thermald.

9. The greeter

Four files, all under /etc/greetd/, plus a systemd drop-in:

• config.toml — vt = 7, and command = "start-hyprland -- --config /etc/greetd/hyprland.conf". Launching Hyprland directly makes it raise a warning into its on-screen error overlay.
• hyprland.conf — a minimal compositor carrying the same monitor = DSI-1, preferred, auto, 1.5, transform, 3, input:touchdevice:transform = 3, and env = GTK_THEME,Adwaita:dark, whose only exec-once runs gtkgreet and then exits.
• gtkgreet.css — theming. Remember GTK CSS rejects percentage units and discards the entire stylesheet on one bad declaration.
• environments — one line: start-hyprland.

sudo usermod -aG video _greetd
sudo usermod -aG input _greetd
sudo usermod -aG render _greetd

The background must live somewhere _greetd can read — /usr/share/backgrounds/, not your home directory, which is mode 0700.

And the safety net, at /etc/systemd/system/greetd.service.d/10-restart-limit.conf:

[Unit]
StartLimitIntervalSec=60
StartLimitBurst=3
[Service]
RestartSec=2

greetd defaults to Restart=always with a one-second delay; without this, a broken greeter respawns forever and seizes VT 7 each time, making it very hard to reach a console to fix it.

10. Networking

If the installer left you on ifupdown (a hand-rolled wpa_supplicant plus dhcpcd), migrating to NetworkManager gives you roaming, nmtui, and a working click target in the status bar. The PSK is already on disk in /etc/network/interfaces — mode 0600, so read it with sudo; a plain cat fails with permission denied and prints nothing, which is easy to misread as an empty file.

Write the NetworkManager profile before tearing down the old stack, and have the migration roll itself back if connectivity does not return.

11. The microphone

Non-negotiable before any video call on this hardware:

amixer -c 0 sset "Internal Mic Boost" 0
wpctl set-volume @DEFAULT_AUDIO_SOURCE@ 0.40
sudo alsactl store

12. Verify, rather than assume

hyprctl configerrors                       # empty
cat /sys/power/mem_sleep                   # s2idle [deep]
cat /sys/devices/system/cpu/cpu0/cpufreq/energy_performance_preference   # power
systemctl --failed                         # 0 units
systemctl is-active greetd thermald powertop mem-sleep-deep
wpctl status                               # a sink and a source
v4l2-ctl -d /dev/video0 --stream-mmap --stream-count=1 --stream-to=/tmp/f.raw

Then reboot once and confirm the greeter comes up on its own. Everything in this post that broke, broke because something was assumed rather than checked.

Appendix — everything installed, and the backports situation

Why backports is involved at all

Debian 13 "trixie" is a stable release, and stable does not carry Hyprland or its satellite tools. They live in trixie-backports — packages built from testing/unstable and recompiled against stable's libraries.

On this machine backports was already enabled before the desktop build started, so nothing in this post required editing apt sources. For anyone reproducing it from a clean Debian 13, this is the setup:

echo 'deb http://deb.debian.org/debian trixie-backports main' \
    | sudo tee /etc/apt/sources.list.d/trixie-backports.list
sudo apt update

The full source list on this machine, for reference:

# /etc/apt/sources.list
deb http://deb.debian.org/debian/ trixie main non-free-firmware
deb http://security.debian.org/debian-security trixie-security main non-free-firmware
deb http://deb.debian.org/debian/ trixie-updates main non-free-firmware

# /etc/apt/sources.list.d/trixie-backports.list
deb http://deb.debian.org/debian trixie-backports main

The mechanic worth understanding: priority 100

Backports is marked NotAutomatic, which apt translates into priority 100 — below the default 500 of the normal archives:

100 http://deb.debian.org/debian trixie-backports/main amd64 Packages
    release o=Debian Backports,a=stable-backports,n=trixie-backports,...
500 http://deb.debian.org/debian trixie-updates/main amd64 Packages

That has two consequences, and they are easy to get backwards:

Enabling backports will not silently upgrade anything. Nothing already installed from stable gets pulled forward. fwupd on this machine exists in both archives and stayed on the stable version (2.0.20-1~deb13u1) precisely because 500 beats 100. This is the whole point of the design — you opt in per package, not wholesale.

But you do not always need -t. If a package exists only in backports, its version is the only candidate and apt installs it without argument. That is why apt install hyprlock worked here with no flags: there is no hyprlock in trixie main at all.

You need -t trixie-backports when the package exists in both and you want the newer one — and critically, that flag also lets apt satisfy dependencies from backports. That is how the graphics stack on this machine ended up modernised: installing Hyprland from backports dragged mesa 26.1.2, PipeWire 1.4.9, WirePlumber 0.5.12 and libxkbcommon 1.13.1 forward with it, all of which do exist in stable at older versions.

Forty-eight packages on this system now come from backports. The load-bearing ones:

This is also, indirectly, the reason so much of this post is about version drift: running a compositor from backports on a stable base means the software is considerably newer than most of the documentation written about it.

The full install, in one command

Everything added during this build. Debian shipped hyprland, waybar, mako, foot, fuzzel, grim, slurp, wl-clipboard, brightnessctl, powertop, jq, git, mosh, tmux and rsync already:

sudo apt update && sudo apt install -y \
    hyprlock hypridle hyprpaper cliphist \
    greetd gtkgreet \
    network-manager thermald fwupd iw \
    imv zathura swappy pcmanfm \
    wf-recorder vainfo intel-media-va-driver \
    thunderbird telegram-desktop \
    starship \
    util-linux-extra v4l-utils alsa-utils libglib2.0-bin

Of those, four resolve to backports automatically because they have no stable version — hyprlock, hypridle, hyprpaper and telegram-desktop. The rest come from trixie main. No -t flag is needed for any of them.

The last line is diagnostics that earned their place during the build:

If you would rather not install the diagnostics permanently, everything except alsa-utils can be removed afterwards — but alsactl is what persists the mixer settings across reboots, so that one should stay.

Fonts, which are not packaged

MesloLGS NF is not in Debian. Installed per-user, no root required:

mkdir -p ~/.local/share/fonts && cd ~/.local/share/fonts
base=https://github.com/romkatv/powerlevel10k-media/raw/master
for style in Regular Bold Italic "Bold%20Italic"; do
    curl -fsSL "$base/MesloLGS%20NF%20${style}.ttf" \
         -o "MesloLGS NF ${style//%20/ }.ttf"
done
fc-cache -f ~/.local/share/fonts

Debian's fonts-font-awesome is worth having as well, but note the trap from Part 2: it installs a family named FontAwesome, not Font Awesome 6 Free.

Appendix — the finished hyprland.conf

The thirteen lines at the top of this post grew into this. Reproduced in full, because most of the comments exist to record why a line is the way it is — which silent failure it prevents, or which 0.55 syntax change it survives. This file and every other one below are in the repo: github.com/mattnovakemail/minibook-x-hyprland.

###############################################################################
# MONITOR  --  1200x1920 DSI panel, rotated 270 deg -> 1920x1200 landscape
#
# The panel is 10.5" at 1920x1200 = ~216 DPI, i.e. 2.25x a normal 96 DPI
# display, which is why everything renders tiny at scale 1. Scale 1.5 gives
# 1280x800 logical (an exact integer division, so no blurry resampling) and
# ~144 DPI effective. Every Wayland client scales with this -- GTK apps,
# Firefox, dialogs, cursors -- not just text.
###############################################################################
monitor = DSI-1, preferred, auto, 1.5, transform, 3

# Hyprland does not inherit the login shell's PATH, so ~/.local/bin is absent
# and any bind calling a script there silently does nothing.
# Telegram is Qt5, which defaults to xcb -> XWayland -> soft at 1.5x scale.
# ";xcb" is a fallback so a Qt app still starts if the wayland plugin fails.
env = QT_QPA_PLATFORM,wayland;xcb
env = QT_WAYLAND_DISABLE_WINDOWDECORATION,1
env = QT_AUTO_SCREEN_SCALE_FACTOR,1

env = XCURSOR_SIZE,24
env = HYPRCURSOR_SIZE,24
env = PATH,/home/YOUR-USER/.config/scripts:/home/YOUR-USER/.local/bin:/usr/local/bin:/usr/bin:/bin:/usr/local/games:/usr/games

$scripts  = /home/YOUR-USER/.config/scripts
$mod      = SUPER
$terminal = foot
$menu     = fuzzel
$browser  = firefox

###############################################################################
# AUTOSTART
###############################################################################
# The systemd/dbus user manager outlives a session and keeps the OLD
# WAYLAND_DISPLAY, which makes xdg-desktop-portal-gtk fail to start and costs
# waybar a 25s timeout on every launch. Hand it the live session's values first.
exec-once = dbus-update-activation-environment --systemd WAYLAND_DISPLAY XDG_CURRENT_DESKTOP XDG_SESSION_TYPE HYPRLAND_INSTANCE_SIGNATURE
exec-once = systemctl --user restart xdg-desktop-portal-gtk.service

exec-once = hyprpaper
exec-once = waybar
exec-once = mako
exec-once = pgrep -x hypridle >/dev/null || hypridle    # singleton: global hardware
exec-once = pgrep -f "type text --watch cliphist" >/dev/null || wl-paste --type text --watch cliphist store
exec-once = pgrep -f "type image --watch cliphist" >/dev/null || wl-paste --type image --watch cliphist store

###############################################################################
# INPUT
###############################################################################
input {
	kb_layout = us
	follow_mouse = 1
	sensitivity = 0

	touchpad {
		natural_scroll = true
		tap-to-click = true
		drag_lock = true
		disable_while_typing = true
		scroll_factor = 0.6
	}

	# Touchscreen must match the panel rotation, or taps land in the wrong spot.
	touchdevice {
		transform = 3
	}
}

# Three fingers sideways = change desktop; four fingers = scratchpad.
gesture = 3, horizontal, workspace
gesture = 4, up, special, magic

###############################################################################
# LOOK
###############################################################################
general {
	gaps_in = 3
	gaps_out = 5
	border_size = 2
	col.active_border = rgba(7aa2f7ff) rgba(bb9af7ff) 45deg
	col.inactive_border = rgba(2a2f41aa)
	resize_on_border = true
	layout = dwindle
}

decoration {
	rounding = 6

	blur {
		enabled = true
		size = 4
		passes = 2
	}

	shadow {
		enabled = true
		range = 12
		render_power = 3
		color = rgba(00000055)
	}
}

animations {
	enabled = true
	bezier = snap, 0.05, 0.9, 0.1, 1.05
	animation = windows, 1, 4, snap, popin 80%
	animation = border, 1, 8, default
	animation = fade, 1, 5, default
	animation = workspaces, 1, 4, snap, slide
}

dwindle {
	preserve_split = true
	smart_resizing = true
}

misc {
	# If the lock screen ever dies while holding the session lock, Hyprland
	# normally leaves the session locked with no locker ("lockdead") and the
	# only way out is a reboot. This lets a freshly launched hyprlock adopt the
	# orphaned lock instead. Costs nothing; saves a forced reboot.
	allow_session_lock_restore = true

	force_default_wallpaper = 0
	disable_hyprland_logo = true
	background_color = rgb(1a1b26)
	focus_on_activate = true
}

###############################################################################
# WINDOW RULES
###############################################################################
# Hyprland 0.55 rule syntax: <field> = <value>, match:<field> = <value>
windowrule = suppress_event = maximize, match:class = .*
windowrule = float = true, match:class = ^(pavucontrol|nm-connection-editor|blueman-manager)$
windowrule = float = true, match:title = ^(Open File|Save File|Choose Files|Open Folder)$
windowrule = float = true, match:class = ^(foot-float)$
windowrule = size = 60% 55%, match:class = ^(foot-float)$
windowrule = center = true, match:class = ^(foot-float)$
# Give the big apps their own desktops -- at 1280x800 logical, tiling four
# windows on one workspace leaves each ~628x374, which is unusable.
windowrule = workspace = 2, match:class = ^(firefox|firefox-esr)$
windowrule = workspace = 3, match:class = ^(thunderbird)$
windowrule = workspace = 4, match:class = ^(org\.telegram\.desktop)$

# Stop empty XWayland drag-shadow windows from stealing focus
windowrule = no_focus = true, match:class = ^$, match:title = ^$, match:xwayland = true, match:float = true, match:fullscreen = false, match:pin = false

###############################################################################
# KEYBINDS -- apps
###############################################################################
bind = $mod, Return, exec, $terminal
bind = $mod, D, exec, $menu
bind = $mod, B, exec, $browser
bind = $mod, E, exec, pcmanfm        # file manager
bind = $mod SHIFT, Return, exec, $terminal --app-id=foot-float

###############################################################################
# KEYBINDS -- window management
###############################################################################
bind = $mod, Q, killactive                          # close the focused window
bind = $mod, F, fullscreen, 0                       # true fullscreen
bind = $mod SHIFT, F, fullscreen, 1                 # maximize (keeps bar + gaps)
bind = $mod CTRL, F, fullscreenstate, -1, 2         # fake fullscreen (games)
bind = $mod, V, togglefloating
bind = $mod SHIFT, space, togglefloating
bind = $mod, P, pseudo
bind = $mod, Y, layoutmsg, togglesplit
bind = $mod, C, centerwindow
bind = $mod, T, pin                                 # keep floating window on top

# Move focus
bind = $mod, left,  movefocus, l
bind = $mod, right, movefocus, r
bind = $mod, up,    movefocus, u
bind = $mod, down,  movefocus, d
bind = $mod, H, movefocus, l
bind = $mod, K, movefocus, u
bind = $mod, L, movefocus, r
bind = $mod, J, movefocus, d

# Move the window itself
bind = $mod SHIFT, left,  movewindow, l
bind = $mod SHIFT, right, movewindow, r
bind = $mod SHIFT, up,    movewindow, u
bind = $mod SHIFT, down,  movewindow, d
bind = $mod SHIFT, H, movewindow, l
bind = $mod SHIFT, K, movewindow, u
bind = $mod SHIFT, L, movewindow, r
bind = $mod SHIFT, J, movewindow, d

# Resize (held down = repeats)
binde = $mod ALT, left,  resizeactive, -40 0
binde = $mod ALT, right, resizeactive, 40 0
binde = $mod ALT, up,    resizeactive, 0 -40
binde = $mod ALT, down,  resizeactive, 0 40
binde = $mod ALT, H, resizeactive, -40 0
binde = $mod ALT, K, resizeactive, 0 -40
binde = $mod ALT, L, resizeactive, 40 0
binde = $mod ALT, J, resizeactive, 0 40

# Mouse: SUPER + left-drag moves, SUPER + right-drag resizes
bindm = $mod, mouse:272, movewindow
bindm = $mod, mouse:273, resizewindow

###############################################################################
# KEYBINDS -- 5 desktops
###############################################################################
bind = $mod, 1, workspace, 1
bind = $mod, 2, workspace, 2
bind = $mod, 3, workspace, 3
bind = $mod, 4, workspace, 4
bind = $mod, 5, workspace, 5

# Send the window to a desktop and follow it
bind = $mod SHIFT, 1, movetoworkspace, 1
bind = $mod SHIFT, 2, movetoworkspace, 2
bind = $mod SHIFT, 3, movetoworkspace, 3
bind = $mod SHIFT, 4, movetoworkspace, 4
bind = $mod SHIFT, 5, movetoworkspace, 5

# Send the window to a desktop and stay put
bind = $mod CTRL, 1, movetoworkspacesilent, 1
bind = $mod CTRL, 2, movetoworkspacesilent, 2
bind = $mod CTRL, 3, movetoworkspacesilent, 3
bind = $mod CTRL, 4, movetoworkspacesilent, 4
bind = $mod CTRL, 5, movetoworkspacesilent, 5

# Cycle desktops
bind = $mod, Tab, workspace, e+1
bind = $mod SHIFT, Tab, workspace, e-1
bind = $mod CTRL, right, workspace, e+1
bind = $mod CTRL, left, workspace, e-1
bind = $mod, grave, workspace, previous
bind = $mod, mouse_down, workspace, e+1
bind = $mod, mouse_up, workspace, e-1

# Scratchpad
bind = $mod, S, togglespecialworkspace, magic
bind = $mod ALT, S, movetoworkspace, special:magic

###############################################################################
# KEYBINDS -- screenshots (region -> clipboard AND ~/Pictures/Screenshots)
###############################################################################
bind = $mod SHIFT, S, exec, $scripts/screenshot region
bind = $mod CTRL SHIFT, S, exec, $scripts/screenshot region --edit    # annotate before saving
bind = , Print, exec, $scripts/screenshot screen
bind = SHIFT, Print, exec, $scripts/screenshot window
bind = $mod, Print, exec, $scripts/screenshot window

###############################################################################
# KEYBINDS -- hardware keys
###############################################################################
bindel = , XF86AudioRaiseVolume, exec, wpctl set-volume -l 1.4 @DEFAULT_AUDIO_SINK@ 5%+
bindel = , XF86AudioLowerVolume, exec, wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%-
bindl  = , XF86AudioMute, exec, wpctl set-mute @DEFAULT_AUDIO_SINK@ toggle
bindl  = , XF86AudioMicMute, exec, wpctl set-mute @DEFAULT_AUDIO_SOURCE@ toggle
bindel = , XF86MonBrightnessUp, exec, brightnessctl -e4 -n2 set 5%+
bindel = , XF86MonBrightnessDown, exec, brightnessctl -e4 -n2 set 5%-

# Lid closed -> lock + screen off, lid open -> screen on
bindl = , switch:on:Lid Switch, exec, loginctl lock-session && hyprctl dispatch dpms off
bindl = , switch:off:Lid Switch, exec, hyprctl dispatch dpms on

###############################################################################
# KEYBINDS -- session
###############################################################################
bind = $mod, Escape, exec, loginctl lock-session      # lock the screen
bind = $mod SHIFT, V, exec, cliphist list | fuzzel --dmenu --width 70 | cliphist decode | wl-copy
bind = $mod CTRL SHIFT, V, exec, cliphist wipe && notify-send "Clipboard history cleared"
# Screen recording (toggle -- press again to stop and finalise the file)
bind = $mod ALT, R, exec, $scripts/record screen
bind = $mod ALT SHIFT, R, exec, $scripts/record region
bind = $mod ALT, A, exec, $scripts/record screen --audio

bind = $mod SHIFT, R, exec, hyprctl reload
bind = $mod SHIFT, Q, exit                          # quit Hyprland
bind = $mod SHIFT, E, exit
bind = $mod, slash, exec, $terminal --app-id=foot-float -e $scripts/hypr-keys

Appendix — every remaining config file

The full hyprland.conf is in the appendix above. These are the rest, verbatim from the running system, so the guide is self-contained. Remember to substitute /home/YOUR-USER where it appears.

Compositor

~/.config/hypr/hyprlock.conf

###############################################################################
# hyprlock -- lock screen
#
# Styled to match the fuzzel launcher (Super+D): a translucent #1a1b26 panel
# with a 2px iris border and 14px radius, MesloLGS NF throughout, purple
# accents.
#
# NOTE: hyprlock draws in PHYSICAL pixels and ignores the compositor's 1.5x
# scale -- measured, a 440px panel came out 440px wide on the 1920px panel.
# So every size here is ~1.5x what the same element would be in a scaled
# Wayland client like fuzzel or waybar.
###############################################################################

grace = 2                        # 2s to abort the lock by moving/typing

general {
	hide_cursor = true
	ignore_empty_input = true
}

auth {
	pam {
		enabled = true
	}
}

background {
	monitor =
	path = ~/Pictures/wallpaper.png
	blur_passes = 3
	blur_size = 8
	brightness = 0.7
	contrast = 0.9
	vibrancy = 0.17
}

# The panel, matching fuzzel's frame. Declared first so everything else
# renders on top of it.
shape {
	monitor =
	size = 780, 430
	color = rgba(1a1b26f2)
	rounding = 14
	border_size = 2
	border_color = rgba(bb9af7ff)
	position = 0, 0
	halign = center
	valign = center
}

# Clock
label {
	monitor =
	text = cmd[update:1000] date +"%H:%M"
	color = rgba(c0caf5ff)
	font_size = 92
	font_family = MesloLGS NF Bold
	position = 0, 108
	halign = center
	valign = center
}

# Date
label {
	monitor =
	text = cmd[update:60000] date +"%A, %d %B"
	color = rgba(bb9af7ff)
	font_size = 22
	font_family = MesloLGS NF
	position = 0, 34
	halign = center
	valign = center
}

# Who you are, and how much charge is left
label {
	monitor =
	text = cmd[update:30000] printf '%s  ·  %s%%' "$USER" "$(cat /sys/class/power_supply/BAT0/capacity)"
	color = rgba(565f89ff)
	font_size = 16
	font_family = MesloLGS NF
	position = 0, 2
	halign = center
	valign = center
}

# Password field -- fuzzel's input frame: iris border, 14px radius,
# translucent #1a1b26 fill
input-field {
	monitor =
	size = 580, 66
	outline_thickness = 2
	dots_size = 0.24
	dots_spacing = 0.32
	dots_center = true
	outer_color = rgba(bb9af7ff)
	inner_color = rgba(1a1b26f2)
	font_color = rgba(c0caf5ff)
	font_family = MesloLGS NF
	fade_on_empty = false
	placeholder_text = <span foreground="##565f89">type to unlock</span>
	fail_color = rgba(f7768eff)
	fail_text = <span foreground="##f7768e">$FAIL  ($ATTEMPTS)</span>
	check_color = rgba(7aa2f7ff)
	rounding = 14
	position = 0, -110
	halign = center
	valign = center
}

~/.config/hypr/hypridle.conf

###############################################################################
# hypridle -- idle management
#
# Deliberately gentle. A dim that looks like a dead screen, or a surprise
# lock, is worse than a slightly warmer battery.
###############################################################################
general {
	lock_cmd = pidof hyprlock || hyprlock          # never stack two lockers
	before_sleep_cmd = loginctl lock-session
	after_sleep_cmd = hyprctl dispatch dpms on
}

# 10 min -- dim, but stay clearly readable. Any input restores.
listener {
	timeout = 600
	on-timeout = brightnessctl -s set 30%
	on-resume = brightnessctl -r
}

# 20 min -- screen off
listener {
	timeout = 1200
	on-timeout = hyprctl dispatch dpms off
	on-resume = hyprctl dispatch dpms on
}

# No auto-lock and no auto-suspend. Lock manually with Super+Escape.
# Closing the lid still locks (see hyprland.conf).

~/.config/hypr/hyprpaper.conf

splash = false

wallpaper {
	monitor = DSI-1
	path = /home/YOUR-USER/Pictures/wallpaper.png
	fit_mode = cover
}

Bar, launcher, notifications

~/.config/waybar/config.jsonc

{
	"layer": "top",
	"position": "top",
	"height": 28,
	"spacing": 6,

	"modules-left":   ["hyprland/workspaces", "hyprland/submap"],
	"modules-center": ["hyprland/window"],
	"modules-right":  ["custom/recording", "tray", "wireplumber", "backlight", "network", "battery", "clock"],

	"hyprland/workspaces": {
		"format": "{icon}",
		"format-icons": {
			"1": "1", "2": "2", "3": "3", "4": "4", "5": "5",
			"special": ""
		},
		"persistent-workspaces": { "*": 5 },
		"on-click": "activate",
		"on-scroll-up": "hyprctl dispatch workspace e+1",
		"on-scroll-down": "hyprctl dispatch workspace e-1"
	},

	"hyprland/window": {
		"format": "{title}",
		"max-length": 60,
		"separate-outputs": true
	},

	"custom/recording": {
		"exec": "pgrep -x wf-recorder >/dev/null && echo '{\"text\":\"REC\",\"tooltip\":\"recording -- Super+Alt+R to stop\"}' || echo '{}'",
		"return-type": "json",
		"interval": 2,
		"format": "{}",
		"on-click": "/home/YOUR-USER/.config/scripts/record"
	},

	"tray": { "icon-size": 14, "spacing": 8 },

	"wireplumber": {
		"format": "{icon}  {volume}%",
		"format-muted": "  muted",
		"format-icons": ["", "", ""],
		"on-click": "wpctl set-mute @DEFAULT_AUDIO_SINK@ toggle",
		"on-scroll-up": "wpctl set-volume -l 1.4 @DEFAULT_AUDIO_SINK@ 5%+",
		"on-scroll-down": "wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%-"
	},

	"backlight": {
		"device": "intel_backlight",
		"format": "  {percent}%",
		"on-scroll-up": "brightnessctl -e4 -n2 set 5%+",
		"on-scroll-down": "brightnessctl -e4 -n2 set 5%-"
	},

	"network": {
		"format-wifi": "  {signalStrength}%",
		"format-ethernet": "  {ipaddr}",
		"format-disconnected": "  off",
		"tooltip-format-wifi": "{essid}  ({signalStrength}%)\n{ipaddr}",
		"on-click": "foot -e nmtui"
	},

	"battery": {
		"states": { "warning": 25, "critical": 10 },
		"format": "{icon}  {capacity}%",
		"format-charging": "  {capacity}%",
		"format-plugged": "  {capacity}%",
		"format-icons": ["", "", "", "", ""],
		"tooltip-format": "{timeTo}  ({power:.1f} W)"
	},

	"clock": {
		"format": "{:%a %d %b  %H:%M}",
		"tooltip-format": "<tt><small>{calendar}</small></tt>",
		"calendar": {
			"mode": "month",
			"format": { "today": "<span color='#7aa2f7'><b>{}</b></span>" }
		}
	}
}

~/.config/waybar/style.css

* {
	font-family: "JetBrains Mono", "FontAwesome", monospace;
	font-size: 13px;
	min-height: 0;
	border: none;
	border-radius: 0;
}

window#waybar {
	background: rgba(26, 27, 38, 0.92);
	color: #c0caf5;
}

#workspaces button {
	padding: 0 11px;
	color: #565f89;
	background: transparent;
}

#workspaces button.active {
	color: #1a1b26;
	background: #7aa2f7;
	border-radius: 6px;
}

#workspaces button.urgent {
	color: #1a1b26;
	background: #f7768e;
	border-radius: 6px;
}

#workspaces button:hover {
	background: #2a2f41;
	color: #c0caf5;
	border-radius: 6px;
}

#window {
	color: #a9b1d6;
}

window#waybar.empty #window {
	background: transparent;
}

#clock,
#battery,
#backlight,
#network,
#wireplumber,
#tray {
	padding: 0 10px;
	color: #c0caf5;
}

#clock       { color: #7aa2f7; font-weight: bold; }
#backlight   { color: #e0af68; }
#wireplumber { color: #9ece6a; }
#network     { color: #7dcfff; }
#battery     { color: #9ece6a; }

#battery.charging { color: #73daca; }

#battery.warning:not(.charging) { color: #e0af68; }

#battery.critical:not(.charging) {
	color: #f7768e;
	animation: blink 1s steps(2, start) infinite;
}

@keyframes blink {
	to { color: #c0caf5; }
}

#custom-recording {
	color: #1a1b26;
	background: #f7768e;
	padding: 0 9px;
	margin: 4px 2px;
	border-radius: 6px;
	font-weight: bold;
	animation: blink 1.4s steps(2, start) infinite;
}

~/.config/fuzzel/fuzzel.ini

# fuzzel -- Super+D launcher, Tokyo Night to match waybar / hyprlock / starship
[main]
font=MesloLGS NF:size=13
# The compositor runs at 1.5x. dpi-aware=no makes fuzzel scale with the output
# scale factor rather than computing its own DPI, which is what we want here.
dpi-aware=no
icon-theme=Adwaita
icons-enabled=yes
terminal=foot -e
# fzf-style subsequence matching: "tgd" finds Telegram Desktop
match-mode=fzf
use-bold=yes
prompt="󰍉  "
placeholder=type to search
lines=9
width=44
horizontal-pad=26
vertical-pad=20
inner-pad=14
line-height=26
layer=overlay
exit-on-keyboard-focus-loss=yes

[colors]
background=1a1b26f2
text=a9b1d6ff
prompt=bb9af7ff
placeholder=565f89ff
input=c0caf5ff
match=7aa2f7ff
selection=3b4261ff
selection-text=c0caf5ff
selection-match=bb9af7ff
counter=565f89ff
border=bb9af7ff

[border]
width=2
radius=14

~/.config/mako/config

font=JetBrains Mono 10
background-color=#1a1b26f2
text-color=#c0caf5
border-color=#7aa2f7
border-size=2
border-radius=6
padding=10
margin=8
default-timeout=5000
anchor=top-right
max-visible=5

[urgency=critical]
border-color=#f7768e
default-timeout=0

Terminal and prompt

~/.config/foot/foot.ini

[main]
# MesloLGS NF is the typeface and supplies its own Nerd Font glyphs.
# JetBrains Mono stays on as a fallback for anything Meslo lacks.
font=MesloLGS NF:size=16, JetBrains Mono:size=16
pad=8x6

[colors]
alpha=1.0
background=1a1b26
foreground=c0caf5
regular0=15161e
regular1=f7768e
regular2=9ece6a
regular3=e0af68
regular4=7aa2f7
regular5=bb9af7
regular6=7dcfff
regular7=a9b1d6
bright0=414868
bright1=f7768e
bright2=9ece6a
bright3=e0af68
bright4=7aa2f7
bright5=bb9af7
bright6=7dcfff
bright7=c0caf5
selection-background=283457
selection-foreground=c0caf5

[cursor]
color=1a1b26 c0caf5

~/.config/starship.toml

# ~/.config/starship.toml -- Tokyo Night, powerline, two-line.
# Designed for a ~100 column terminal at a large font: the top line carries the
# context, the bottom line is always a clean full-width runway for the command.

add_newline = true
palette = "tokyonight"
command_timeout = 900

format = """
[](fg:abyss)\
$os\
$username\
[](bg:steel fg:abyss)\
$directory\
[](fg:steel)\
$git_branch$git_status\
$nodejs$python$rust$golang$lua$zig$java$docker_context\
$status$jobs\
$cmd_duration\
$line_break\
$character"""

[palettes.tokyonight]
iris   = "#bb9af7"
brand  = "#4f9bff"   # brand accent blue (unused while the pill is iris)
steel  = "#3b4261"
slate  = "#2f3549"
abyss  = "#24283b"
ink    = "#1a1b26"
snow   = "#c0caf5"
haze   = "#565f89"
azure  = "#7aa2f7"
mint   = "#9ece6a"
amber  = "#e0af68"
coral  = "#ff9e64"
rose   = "#f7768e"
sky    = "#7dcfff"
jade   = "#73daca"

###############################################################################
# Identity
###############################################################################
[os]
disabled = false
style = "bg:abyss fg:iris"
format = "[ $symbol ]($style)"

[os.symbols]
Debian = "󰊠"   # nf-md-ghost U+F02A0
#Debian = "󰔉"  # site accent glyph (nf-md-terrain U+F0509)
Ubuntu = "󰕈"
Arch = "󰣇"
Linux = "󰊠"
Macos = "󰀵"

[username]
show_always = false          # only speaks up when it matters: root, or over ssh
style_user = "bg:abyss fg:iris"
style_root = "bg:rose fg:ink bold"
format = "[$user ]($style)"

[hostname]
ssh_only = true
style = "bg:iris fg:ink"
format = "[@$hostname ]($style)"

###############################################################################
# Where you are
###############################################################################
[directory]
style = "bg:steel fg:snow"
format = "[ $path ]($style)[$read_only]($read_only_style)"
truncation_length = 3
truncation_symbol = "…/"
read_only = " 󰌾"
read_only_style = "bg:steel fg:rose"
home_symbol = "󰋜"

[directory.substitutions]
"Documents" = "󰈙"
"Downloads" = "󰉍"
"Pictures"  = "󰋩"
"Music"     = "󰝚"
"Videos"    = "󰕧"
".config"   = "󰒓"
"system"    = "󰒓"

###############################################################################
# Git -- the segment that earns its space
###############################################################################
[git_branch]
symbol = ""
style = "bg:slate fg:mint"
format = " [](fg:slate)[ $symbol $branch ]($style)"
truncation_length = 20
truncation_symbol = "…"

[git_status]
style = "bg:slate fg:amber"
format = "[$all_status$ahead_behind]($style)[](fg:slate)"
conflicted = "󰞇 ${count} "
ahead      = "󰁝${count} "
behind     = "󰁅${count} "
diverged   = "󰃻${ahead_count}󰁅${behind_count} "
up_to_date = ""
untracked  = "󰋗${count} "
stashed    = "󰏗${count} "
modified   = "󰏫${count} "
staged     = "󰐗${count} "
renamed    = "󰑕${count} "
deleted    = "󰍶${count} "

###############################################################################
# Toolchains -- each only appears in a project that actually uses it
###############################################################################
[nodejs]
symbol = "󰎙"
style = "bg:abyss fg:mint"
format = " [](fg:abyss)[$symbol $version ]($style)[](fg:abyss)"

[python]
symbol = "󰌠"
style = "bg:abyss fg:amber"
format = " [](fg:abyss)[$symbol $version ]($style)[](fg:abyss)"
pyenv_version_name = true

[rust]
symbol = "󱘗"
style = "bg:abyss fg:coral"
format = " [](fg:abyss)[$symbol $version ]($style)[](fg:abyss)"

[golang]
symbol = "󰟓"
style = "bg:abyss fg:sky"
format = " [](fg:abyss)[$symbol $version ]($style)[](fg:abyss)"

[lua]
symbol = "󰢱"
style = "bg:abyss fg:azure"
format = " [](fg:abyss)[$symbol $version ]($style)[](fg:abyss)"

[zig]
symbol = ""
style = "bg:abyss fg:coral"
format = " [](fg:abyss)[$symbol $version ]($style)[](fg:abyss)"

[java]
symbol = "󰬷"
style = "bg:abyss fg:rose"
format = " [](fg:abyss)[$symbol $version ]($style)[](fg:abyss)"

[docker_context]
symbol = "󰡨"
style = "bg:abyss fg:sky"
format = " [](fg:abyss)[$symbol $context ]($style)[](fg:abyss)"
only_with_files = true

###############################################################################
# Feedback
###############################################################################
[cmd_duration]
min_time = 2_000
style = "fg:haze italic"
format = " [󱎫 $duration]($style)"
show_milliseconds = false

[character]
success_symbol = "[󰁔](bold mint)"
error_symbol = "[󰁔](bold rose)"
vimcmd_symbol = "[󰁍](bold iris)"

###############################################################################
# Right side
###############################################################################
[battery]
disabled = true   # waybar shows this
format = "[$symbol$percentage]($style) "
full_symbol = "󰁹 "
charging_symbol = "󰂄 "
discharging_symbol = "󰁿 "
unknown_symbol = "󰂑 "
empty_symbol = "󰂎 "

[[battery.display]]
threshold = 15
style = "fg:rose bold"

[[battery.display]]
threshold = 40
style = "fg:amber"

[[battery.display]]
threshold = 100
style = "fg:haze"

[time]
disabled = true   # waybar shows this
time_format = "%H:%M"
style = "fg:haze"
format = "[󰥔 $time]($style)"

[status]
disabled = false
symbol = "󰅙 "
format = " [$symbol$common_meaning$signal_name$maybe_int]($style)"
style = "fg:rose bold"
map_symbol = false
pipestatus = true

[jobs]
symbol = "󰑮"
style = "fg:sky"
format = " [$symbol$number]($style)"
number_threshold = 1

~/.config/starship-tty.toml

# starship-tty.toml -- prompt for the Linux virtual console (TERM=linux)
#
# The kernel console loads PSF fonts, which hold at most 512 glyphs and cannot
# contain Nerd Font Private Use Area codepoints. It also has no truecolor: the
# VT gives you the 16 ANSI colours, so hex values like #bb9af7 are not usable.
#
# This config is therefore deliberately plain: pure ASCII symbols, named ANSI
# colours, no powerline separators, no icons. Same information, nothing that
# renders as a blank box.
#
# ~/.bashrc selects it automatically when TERM=linux; every other terminal gets
# the full ~/.config/starship.toml.

add_newline = true
command_timeout = 900

format = """
$username\
$hostname\
$directory\
$git_branch\
$git_status\
$nodejs$python$rust$golang$lua$zig$java\
$cmd_duration\
$status$jobs\
$line_break\
$character"""

[username]
show_always = true
style_user = "bold cyan"
style_root = "bold red"
format = "[$user]($style)"

[hostname]
ssh_only = false
style = "cyan"
format = "[@$hostname]($style) "

[directory]
style = "bold blue"
format = "[$path]($style)[$read_only]($read_only_style) "
truncation_length = 3
truncation_symbol = ".../"
read_only = " [ro]"
read_only_style = "red"

[git_branch]
symbol = ""
style = "bold green"
format = "[git:$branch]($style) "
truncation_length = 20
truncation_symbol = "..."

[git_status]
style = "yellow"
format = "([$all_status$ahead_behind]($style) )"
conflicted = "!${count} "
ahead = "+${count} "
behind = "-${count} "
diverged = "+${ahead_count}-${behind_count} "
up_to_date = ""
untracked = "?${count} "
stashed = "$${count} "
modified = "~${count} "
staged = "*${count} "
renamed = "r${count} "
deleted = "x${count} "

[nodejs]
symbol = ""
style = "green"
format = "[node:$version]($style) "

[python]
symbol = ""
style = "yellow"
format = "[py:$version]($style) "

[rust]
symbol = ""
style = "red"
format = "[rust:$version]($style) "

[golang]
symbol = ""
style = "cyan"
format = "[go:$version]($style) "

[lua]
symbol = ""
style = "blue"
format = "[lua:$version]($style) "

[zig]
symbol = ""
style = "yellow"
format = "[zig:$version]($style) "

[java]
symbol = ""
style = "red"
format = "[java:$version]($style) "

[cmd_duration]
min_time = 2_000
style = "bright-black"
format = "[took $duration]($style) "

[status]
disabled = false
symbol = "!"
format = "[$symbol$common_meaning$signal_name$maybe_int]($style) "
style = "bold red"
map_symbol = false
pipestatus = true

[jobs]
symbol = "&"
style = "cyan"
format = "[$symbol$number]($style) "
number_threshold = 1

[character]
success_symbol = "[>](bold green)"
error_symbol = "[>](bold red)"
vimcmd_symbol = "[<](bold purple)"

# Everything below is off on the console: either it needs glyphs, or it is
# noise on an 80-column VT.
[battery]
disabled = true

[time]
disabled = true

[docker_context]
disabled = true

[package]
disabled = true

Scripts (~/.config/scripts, all chmod +x)

~/.config/scripts/screenshot

#!/usr/bin/env bash
# screenshot [region|window|screen] [--edit]
#   always: copies to clipboard AND saves to ~/Pictures/Screenshots
#   --edit: opens swappy first to crop / annotate / redact before saving
set -euo pipefail

mode="${1:-region}"
edit="${2:-}"
dir="$HOME/Pictures/Screenshots"
mkdir -p "$dir"
file="$dir/$(date +%Y-%m-%d_%H-%M-%S).png"

notify() { command -v notify-send >/dev/null && notify-send -t 2500 "$@" || true; }

case "$mode" in
	region)
		geom=$(slurp -d) || exit 0          # Esc -> quiet exit
		grim -g "$geom" "$file"
		;;
	window)
		geom=$(hyprctl activewindow -j \
			| jq -r '"\(.at[0]),\(.at[1]) \(.size[0])x\(.size[1])"')
		grim -g "$geom" "$file"
		;;
	screen)
		grim "$file"
		;;
	*)
		echo "usage: screenshot [region|window|screen] [--edit]" >&2
		exit 1
		;;
esac

if [ "$edit" = "--edit" ]; then
	# swappy writes the edited result back over the same path on save
	swappy -f "$file" -o "$file"
fi

wl-copy --type image/png < "$file"
notify "Screenshot copied" "$(basename "$file")"

~/.config/scripts/record

#!/usr/bin/env bash
# record [region|screen] [--audio|--mic]   -- toggle screen recording
#
#   record            toggle: full screen, no audio
#   record region     toggle: pick an area with slurp
#   record screen --audio   full screen + system audio (what you hear)
#   record screen --mic     full screen + microphone
#
# Running it again while a recording is active STOPS it, whatever the args.
#
# Encoding is VAAPI h264 on the iGPU. On a 6W N150, software x264 at 1920x1200
# would peg the CPU and cook the battery; the hardware encoder is near-free.
set -uo pipefail

dir="$HOME/Videos/Recordings"
mkdir -p "$dir"

notify() { command -v notify-send >/dev/null && notify-send -t 2500 "$@" || true; }

# --- stop an in-flight recording -------------------------------------------
# wf-recorder MUST get SIGINT, not SIGTERM/SIGKILL: it finalises the MP4
# container (moov atom) on interrupt. Killed any harder, the file is unplayable.
if pgrep -x wf-recorder >/dev/null; then
	pkill -INT -x wf-recorder
	for _ in $(seq 1 40); do
		pgrep -x wf-recorder >/dev/null || break
		sleep 0.1
	done
	newest=$(ls -t "$dir"/*.mp4 2>/dev/null | head -1)
	if [ -n "$newest" ]; then
		size=$(du -h "$newest" | cut -f1)
		printf '%s' "$newest" | wl-copy 2>/dev/null || true
		notify "Recording saved" "$(basename "$newest")  ($size)  path copied"
	else
		notify "Recording stopped" "no file produced"
	fi
	exit 0
fi

# --- start a new recording --------------------------------------------------
mode="${1:-screen}"
audio="${2:-}"
file="$dir/$(date +%Y-%m-%d_%H-%M-%S).mp4"

args=(-f "$file" -c h264_vaapi -d /dev/dri/renderD128
      --codec-param=qp=24 -m mp4)

case "$mode" in
	region)
		geom=$(slurp -d) || exit 0          # Esc -> quiet exit
		args+=(-g "$geom")
		;;
	screen) ;;
	*)
		echo "usage: record [region|screen] [--audio|--mic]" >&2
		exit 1
		;;
esac

case "$audio" in
	--audio)
		# .monitor of the default sink = system audio, not the microphone
		sink=$(wpctl inspect @DEFAULT_AUDIO_SINK@ 2>/dev/null \
			| sed -n 's/.*node\.name = "\(.*\)".*/\1/p' | head -1)
		if [ -n "$sink" ]; then
			args+=(--audio="${sink}.monitor")
		else
			notify "Recording" "could not resolve system audio; recording silent"
		fi
		;;
	--mic)
		args+=(-a)                          # default input device
		;;
	"") ;;
	*)
		echo "unknown audio option: $audio" >&2
		exit 1
		;;
esac

wf-recorder "${args[@]}" >/tmp/wf-recorder.log 2>&1 &
sleep 1.2
if pgrep -x wf-recorder >/dev/null; then
	notify "Recording started" "$mode${audio:+ $audio}  ·  Super+Alt+R to stop"
else
	notify "Recording FAILED" "$(tail -2 /tmp/wf-recorder.log | tr '\n' ' ')"
	exit 1
fi

~/.config/scripts/hypr-keys

#!/usr/bin/env bash
# Pretty-print the Hyprland keybinds cheatsheet.
b=$'\e[1m'; d=$'\e[2m'; c=$'\e[36m'; r=$'\e[0m'
sec(){ printf "\n${b}${c}%s${r}\n" "$1"; }
k(){ printf "  ${b}%-24s${r} %s\n" "$1" "$2"; }

sec "APPS"
k "Super Return"        "terminal"
k "Super Shift Return"  "floating terminal"
k "Super D"             "app launcher"
k "Super B"             "browser"

sec "WINDOWS"
k "Super Q"             "close window"
k "Super F"             "fullscreen"
k "Super Shift F"       "maximize (keeps bar)"
k "Super Ctrl F"        "fake fullscreen"
k "Super V"             "toggle floating"
k "Super C"             "centre window"
k "Super T"             "pin on top"
k "Super P / Super Y"   "pseudotile / toggle split"
k "Super hjkl|arrows"   "move focus"
k "Super Shift hjkl"    "move window"
k "Super Alt hjkl"      "resize window"
k "Super LMB / RMB"     "drag to move / resize"

sec "DESKTOPS (5)"
k "Super 1-5"           "go to desktop"
k "Super Shift 1-5"     "move window there, follow"
k "Super Ctrl 1-5"      "move window there, stay"
k "Super Tab"           "next desktop"
k "Super Shift Tab"     "previous desktop"
k "Super \`"             "last desktop"
k "Super scroll"        "cycle desktops"
k "3 fingers sideways"  "cycle desktops"
k "Super S"             "scratchpad"
k "Super Alt S"         "send to scratchpad"

sec "SCREENSHOTS  (clipboard + ~/Pictures/Screenshots)"
k "Super Shift S"       "select a region"
k "Print"               "whole screen"
k "Shift Print"         "active window"

sec "SCREEN RECORDING  (~/Videos/Recordings, toggle)"
k "Super Alt R"         "record whole screen"
k "Super Alt Shift R"   "record a region"
k "Super Alt A"         "record screen + system audio"
k "  press again"       "stops and finalises the file"

sec "CLIPBOARD"
k "Super Shift V"       "clipboard history"
k "Super Ctrl Shift V"  "wipe clipboard history"

sec "IF THE LOCK SCREEN EVER HANGS"
k "Ctrl+Alt+F2"         "switch to a text console, log in"
k "  then run:"         "hyprctl -i 0 dispatch exec hyprlock"
k "  "                  "(allow_session_lock_restore lets it adopt the dead lock)"

sec "SESSION"
k "Super Escape"        "lock the screen"
k "Super Shift R"       "reload config"
k "Super Shift Q"       "quit Hyprland"
echo
read -rsn1 -p "  press any key to close "

Greeter (these live in /etc/greetd/, root-owned)

/etc/greetd/config.toml

[terminal]
# VT 7 keeps tty1-6 free as plain console logins -- the escape hatch if the
# greeter ever fails to come up.
vt = 7

[default_session]
# Launched via the start-hyprland watchdog, not Hyprland directly: launching
# Hyprland bare makes it raise "being launched without start-hyprland" in the
# top-right error overlay, which flashes on the login screen.
# gtkgreet needs a Wayland compositor to live in; Hyprland gives it the correct
# panel rotation and scale. The greeter config exits the compositor on login.
command = "start-hyprland -- --config /etc/greetd/hyprland.conf"
user = "_greetd"

/etc/greetd/hyprland.conf

# Minimal compositor for the login greeter only.
# It exists so gtkgreet inherits the same rotation and 1.5x scale as the real
# session -- a plain cage/gtkgreet greeter cannot rotate this DSI panel.

monitor = DSI-1, preferred, auto, 1.5, transform, 3

env = GTK_THEME,Adwaita:dark

exec-once = gtkgreet -l -b /usr/share/backgrounds/login.png -s /etc/greetd/gtkgreet.css -c start-hyprland; hyprctl dispatch exit

input {
    kb_layout = us
    touchdevice {
        transform = 3
    }
    touchpad {
        natural_scroll = true
        tap-to-click = true
    }
}

general {
    border_size = 0
    gaps_in = 0
    gaps_out = 0
}

decoration {
    rounding = 0
    blur {
        enabled = false
    }
    shadow {
        enabled = false
    }
}

animations {
    enabled = false
}

misc {
    force_default_wallpaper = 0
    disable_hyprland_logo = true
    background_color = rgb(1a1b26)
}

/etc/greetd/gtkgreet.css

/* Login screen styled to match hyprlock.
 *
 * gtkgreet builds its own widget tree (label beside entry, session combo,
 * "Log in" button), so this cannot reproduce hyprlock's exact vertical stack.
 * What it does match: the wallpaper treatment, palette, typography, the big
 * clock, and the blue-bordered input field -- so the two read as one design.
 *
 * Sizes are LOGICAL px; the greeter compositor runs at scale 1.5.
 */

window {
    background-color: #1a1b26;
}

/* No margins here: symmetric margins visibly shifted the whole block right of
 * centre, and matching hyprlock's centred layout matters more than a narrower
 * field. hyprlock floats its text straight on the wallpaper, so no card. */
box#body {
    background-color: transparent;
    border: none;
    box-shadow: none;
    padding: 0;
}

/* Big clock -- hyprlock's 96px physical -> 64 logical */
label#clock {
    color: #c0caf5;
    font-family: "JetBrains Mono ExtraBold", "JetBrains Mono", monospace;
    font-weight: 800;
    font-size: 64px;
    margin-bottom: 18px;
    text-shadow: 0 2px 14px rgba(0, 0, 0, 0.6);
}

/* "Username:" -- hyprlock's muted secondary text */
label {
    color: #565f89;
    font-family: "JetBrains Mono", monospace;
    font-size: 13px;
    margin-right: 10px;
    text-shadow: 0 1px 6px rgba(0, 0, 0, 0.5);
}

/* hyprlock's input-field: 2px #7aa2f7, #1a1b26e6 fill, 8px radius */
entry {
    background-color: rgba(26, 27, 38, 0.90);
    color: #c0caf5;
    caret-color: #c0caf5;
    border: 2px solid #7aa2f7;
    border-radius: 8px;
    padding: 7px 13px;
    font-family: "JetBrains Mono", monospace;
    font-size: 14px;
    min-height: 32px;
    box-shadow: 0 4px 18px rgba(0, 0, 0, 0.45);
}

entry:focus {
    border-color: #bb9af7;
}

/* hyprlock submits on Enter and shows no button, so keep this understated. */
button {
    background-image: none;
    background-color: rgba(36, 40, 59, 0.75);
    color: #a9b1d6;
    border: 1px solid #3b4261;
    border-radius: 8px;
    padding: 5px 16px;
    font-family: "JetBrains Mono", monospace;
    font-size: 12px;
    margin-top: 12px;
    box-shadow: none;
}

button:hover {
    background-color: #7aa2f7;
    color: #1a1b26;
    border-color: #7aa2f7;
}

/* Session picker: recede, it is not part of the lock-screen look */
#command-selector,
combobox {
    margin-top: 8px;
}

#command-selector entry,
combobox entry,
combobox button {
    background-color: rgba(36, 40, 59, 0.6);
    color: #565f89;
    border: 1px solid #2f3549;
    border-radius: 6px;
    font-size: 12px;
    min-height: 26px;
    box-shadow: none;
}

combobox button:hover {
    background-color: rgba(59, 66, 97, 0.8);
    color: #a9b1d6;
    border-color: #3b4261;
}

/* Auth failure -- hyprlock turns its field #f7768e */
#error_type,
label#error_type {
    color: #f7768e;
    font-weight: bold;
    font-size: 13px;
    text-shadow: 0 1px 6px rgba(0, 0, 0, 0.6);
}

/etc/greetd/environments

start-hyprland

Applications and desktop integration

~/.config/gtk-3.0/settings.ini (copy to gtk-4.0/ as well)

[Settings]
gtk-application-prefer-dark-theme=1
gtk-font-name=Cantarell 11
gtk-cursor-theme-name=Adwaita
gtk-cursor-theme-size=24
gtk-xft-antialias=1
gtk-xft-hinting=1
gtk-xft-hintstyle=hintslight
gtk-xft-rgba=rgb

~/.config/mimeapps.list

[Default Applications]
inode/directory=pcmanfm.desktop
image/png=imv.desktop
image/jpeg=imv.desktop
image/gif=imv.desktop
image/webp=imv.desktop
application/pdf=org.pwmt.zathura.desktop
text/html=firefox-esr.desktop
x-scheme-handler/http=firefox-esr.desktop
x-scheme-handler/https=firefox-esr.desktop

~/.config/libfm/libfm.conf (write while pcmanfm is NOT running)

# Configuration file for the libfm version 1.4.0.
# Autogenerated file, don't edit, your changes will be overwritten.

[config]
single_click=0
middle_click=0
use_trash=1
confirm_del=1
confirm_trash=1
advanced_mode=0
si_unit=0
force_startup_notify=1
date_iso_8601=0
backup_as_hidden=1
no_usb_trash=1
no_child_non_expandable=0
show_full_names=0
only_user_templates=0
template_run_app=0
template_type_once=0
auto_selection_delay=600
drop_default_action=auto
defer_content_test=0
quick_exec=0
show_internal_volumes=0
thumbnail_local=1
thumbnail_max=0
smart_desktop_autodrop=1

[ui]
big_icon_size=64
small_icon_size=24
pane_icon_size=24
thumbnail_size=160
show_thumbnail=1
shadow_hidden=0

[places]
places_home=1
places_desktop=1
places_root=0
places_computer=0
places_trash=1
places_applications=1
places_network=0
places_unmounted=1

~/.config/swappy/config

[Default]
save_dir=$HOME/Pictures/Screenshots
save_filename_format=swappy-%Y%m%d-%H%M%S.png
show_panel=true
line_size=5
text_size=20
text_font=JetBrains Mono
paint_mode=brush
early_exit=false
fill_shape=false

~/.ssh/config

Host *
    ServerAliveInterval 20
    ServerAliveCountMax 3
    TCPKeepAlive no
    ControlMaster auto
    ControlPath ~/.ssh/cm-%r@%h:%p
    ControlPersist 10m
    AddKeysToAgent yes
    IdentityFile ~/.ssh/id_ed25519
    HashKnownHosts no

Generate the key with ssh-keygen -t ed25519 -C "$(whoami)@$(hostname)", and chmod 600 ~/.ssh/config.

~/.bashrc — prompt selection

Appended to the end. The TERM=linux branch is what keeps the prompt readable on a virtual console, where Nerd Font glyphs cannot render:

if command -v starship >/dev/null 2>&1; then
    if [ "$TERM" = "linux" ]; then
        export STARSHIP_CONFIG="$HOME/.config/starship-tty.toml"
    fi
    eval "$(starship init bash)"
fi

Written on the machine it describes: CHUWI MiniBook X, Intel N150, 12 GB LPDDR5, Debian 13 trixie, Hyprland 0.55.2, 216 DPI at 1.5× scale, S3 deep sleep, 3.57 W idle.